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INTRODUCTION 



The purpose of this document is to introduce you to VAX/VMS. 
The document is divided into chapters, where each chapter 
discusses a different aspect of VAX/VMS from the user's point 
of view. 

Chapter 1 provides an overview of the user's environment, 
discussing the software and hardware available with VAX/VMS. 

Chapter 2 gets you started, by discussing how to log in and 
out, use the terminal, enter commands, get help when needed, 
and obtain information about or modify the user environment. 

Chapter 3 discusses file naming conventions, directory 
structure, use of defaults, and deciphering error messages. 

Chapter 4 discusses file creation using the EDT editor, and 
file manipulation commands. 

Chapter 5 discusses program development in general, including 
program examples for several languages supported on VAX/VMS 
(MACRO, FORTRAN, COBOL, BASIC, PASCAL). The VAX-11 Symbolic 
Debugger is also discussed in this chapter. 

Chapter 6 introduces command procedures and symbols, methods 
that can be used to simplify a user session. 

Chapter 7 provides an overview of the RUNOFF text formatter, 
including examples and a summary of popular commands. 

Chapter 8 discusses some other useful utilities, MAIL and 
PHONE. 



CHAPTER 1 
THE USER ENVIRONMENT 



1.0 THE USER ENVIRONMENT 

A computer system consists of two major parts: 
o Hardware 
o Software 

Hardware is a term used to refer to the physical computer, 
which is manufactured in a factory. 

Software is a term used to refer to the programs that 
contain instructions to be performed by the hardware. 

The combination of hardware and software forms a system. 
Many types of hardware and software exist, so computer 
systems do not have to be, and rarely are, identical. 

A user's environment is defined by the combination of 
hardware and software on his/her particular system. Since 
the elements forming each system may not be the same, a user 
of one system will probably work in a different environment 
than a user on another system. 

Each system is managed by a system manager. The system 
manager is familiar with the system environment, and can 
further restrict each user's environment. 
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The hardware on a system is generally divided into three 
parts - the central processing unit (CPU), main memory, and 
peripheral devices. 

The central processing unit is where most of the work is 
done on a computer system. In the VAX family of computers, 
there are four models of the CPU, including the 11-780, 
11-750, and 11-730. The 11-780 model is larger than the 
11-750. The 11-730 is the smallest model. All do the same 
job; some faster than others. There is usually only one 
CPU per system. The 11-782 (larger than the 11-780) uses 
two CPU's, one as the primary worker, and the other as the 
secondary worker. Work is shared between the two processors 
according to rules set up by the designers. 

Main memory is used for temporary storage of instructions 
and data. Main memory can be installed in units, so the 
amount of memory on a system can vary. Battery backup is 
available so the contents of main memory are not lost in the 
case of a power failure. The system manager can set up the 
system to start automatically after a failure (such as a 
power outage), and restore the contents of memory. 
Therefore, with battery backup, work is rarely lost. 

Peripheral devices include disk drives, magnetic tape units, 
printers, terminals, and card readers. 

Each disk or magnetic tape is referred to as a volume in 
this document. The term device is used to refer to the 
physical equipment where the volume is mounted. 

Disks are used by the system to store currently used 
information. A disk can be placed in a disk drive or stored 
in a cabinet in the same way a record can be played on a 
record player or stored in a cabinet. Although several disk 
drives may be attached to a system, the user's information 
is normally recorded on one disk only, which may be mounted 
in any drive. 

In the same way, a person may own several record players to 
play records on. If a particular song is recorded on one 
record only, the person may play the record on any of the 
players and hear the same song. If the creators of another 
record decided to include the same song, or a variation of 
the song, on their record, the song would be on more than 
one record. In the same way, the same information, or 
different versions of the information, may be stored on more 
than one disk. 
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Magnetic tapes are normally used to store information not in 
current use, to free up storage space on the disks. The 
owner of the disk decides what will be stored on tape and/or 
removed from the disk. 

Many different types of disk and magnetic tape drives can be 
installed as part of a VAX/VMS system. The storage of 
information on disks and magnetic tapes is handled by the 
system and the system manager. This document assumes the 
user will not be handling disks or magnetic tapes. 

Most users of VAX/VMS work with printers and terminals. 

Several types of printers are available. The system manager 

chooses one of the printers on the system to be the default 

printer. All files to be printed are sent to the default 
printer unless the user specifies otherwise. 

Several types of terminals are available. Some have a video 
screen, such as the VT52 and VT100. Others are hardcopy 
terminals using paper, such as the LA36 or LA120 (see Figure 
1-1). A standard keyboard is built into all DIGITAL 
terminals (see Figure 1-2) . This document assumes DIGITAL 
terminals are being used. 





A VIDEO 
TERMINAL 



A HARDCOPY 
TERMINAL 



Figure 1-1 



Figure 1-2 
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The software on a system is generally divided into two major 
parts - application software and system software. 

Application software includes programs written by users of 
the system for specific purposes, such as budgeting, 
processing the payroll, running machines, or keeping 
personnel records up-to-date. 

System software includes programs written by the creators of 
the system for such purposes as coordinating users, sharing 
resources, running the hardware, and helping the user 
communicate with the system. 

1.3 RESTRICTING THE USER'S ENVIRONMENT 

A user can be restricted from access to: 

o The system (i.e., not allowed to work on the system) 

o Other users (i.e., so can not affect the work of other 
users) 

o Certain kinds of software (such as system programs) 
o Particular kinds of hardware 

Information about each user is stored in a special file, 
called the User Authorization File (UAF) , on the system. 
The system manager can modify any of information stored 
there to allow the user more access to hardware and 
software, or to restrict the user further. 

The information in the UAF includes: 

o The user's name and password - needed for access to the 
system 

o Privileges - to allow or disallow access to hardware 
and/or software 

o Limits - to restrict the use of system resources 

o UIC - User Identification Code 

o Priority - used by the scheduler to coordinate users - 
on a 'higher priority - first serve' basis 
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When a user logs in, VMS uses this information to create a 
process. A process contains a complete description of the 
user's environment, including all of the information from 
the UAF, what the user is doing, and what part of memory the 
user is working in. Therefore, the process is equivalent to 
the user's environment. Each user works in the context of 
their own process. VMS coordinates, manages, and allocates 
resources to processes, not users. 

Processes are created for the purpose of running programs. 
When a user logs in, a special kind of process is created - 
an interactive process. The term interactive means that the 
user is interacting directly with the system, usually via a 
terminal . 

VMS runs a program for interactive processes as soon as they 
are created. The default program may be changed by the 
system manager, but this document assumes that the program 
is the command language interpreter for the DIGITAL Command 
Language (DCL) . 

The DCL interpreter accepts a DCL command input by the user 
and runs the system program corresponding to that command. 
One DCL command is the RUN command, which can be used to 
execute user programs. After user or system programs have 
completed, VMS runs the DCL interpreter again, so the 
process will not be deleted. (If a program is not executing 
in a process, VMS deletes the process.) 

The user will know if the DCL interpreter program is 
executing by the presence of the DCL prompt, $ (a dollar 
sign) . The dollar sign prompt indicates that the DCL 
interpreter is ready to receive a command from the user. If 
the dollar sign prompt is not present, another program is 
probably executing, and DCL commands should not be input. 

Interactive processes are deleted by VMS when the user logs 
off the system. Resources which were used by that process 
are then available for use by other processes. 
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2.1 LOGGING IN AND OUT 

Before you can log into the system you must obtain 
permission to use the computer. The system manager is 
usually the person to contact. The system manager will give 
you a username and password that will permit you to use the 
facilities of the system. 

Once you have a username and password you can log in. To 
log in to the VAX/VMS system, do one of the following: 

o Press the <RETURN> key on the right side of the keyboard 

o Press the control key <CTRL> on the left side of the 
keyboard. Hold it down and press the C or Y key (both 
achieve the same results) . 

You should see a request for your user name in the format: 
Username: 



If you do not see the prompt: 

o First, check to see if the terminal is plugged 
in and turned on. 

o Then, try again. 

o If you still do not see the prompt, get help 
from your system manager or designated expert. 
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If you received the prompt, enter your user name. The 
system should output another prompt requesting your password 
in the form: 

Password : 

Enter your password. The password does not echo (i.e., you 
can not see what you type) , so type carefully. 

The system should output a welcome message. Some systems 

also output site-specific informational messages. (These 

informational messages can be changed, and added to, by the 
system manager.) 

If the system outputs an error message instead of a 
welcome message: 

o Start over and enter the information more 
carefully 

o If you still receive an error message, notify 
your system manager or designated expert. 
(Sometimes the information recorded in the UAF 
corresponding to your user name is not correct. 
Sometimes the information has not been recorded. 
By notifying the system manager, the problem 
should be corrected so you will not receive any 
more error messages.) 

If the system outputs an informational message such 
as "system busy - try again later", then obey the 
message . 

Assuming you have been successful in logging in, you should 

see the dollar sign prompt, $, at the left side of your 

terminal screen. The $ was output by the DCL interpreter 

program executing in your process. The DCL interpreter is 

ready to receive a valid DCL command. 

One valid DCL command is LOGOUT. If you enter this command, 
your process is deleted and its resources are returned to 
the system. 

$LOGOUT 
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The examples that follow show both a successful and 
unsuccessful attempt to login to the system. 

Example 1 — Successful Login 

<CR> 

Username: SMITH 
Password : 

Welcome to VMS V3.0 

$ 

Example 2 — Unsuccessful Login 

<CR> 

Username: SMITH 

Password: 

User Authorization Failure 
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2.2 SPECIAL TERMINAL KEYS 

A diagram of the standard DIGITAL keyboard can be seen in 

chapter 1, Figure 1-2. The following terminal keys can be 

used while you are logged in to correct errors or modify the 
behavior of programs: 

o DELETE - Used to delete the character just entered on 
the terminal 

For example, If you enter PAPEF when you meant to enter 
PAPER, press the DELETE key after entering the F. 

On a video screen, the F will be erased, leaving the 
cursor after the E. You can then enter the correct 
letter, R. 

When working on a hardcopy terminal, the deleted 

character will be echoed, preceded by a backslash 

character. When the correct letter is entered, another 

backslash character will appear on the paper, followed 
by the new letter. 

PAPEF/F/R 

o BACKSPACE - Do not use I The character entered by this 
key is unacceptable input to the DCL interpreter or a 
compiler. 
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o CTRL - This key is to be used in conjunction with one of 
the following keys by holding it down while pressing one 
of them: 

- C or Y - suspends the current command line or 
currently executing program. The dollar sign prompt 
is then output. 

R - retypes the current input line on the terminal. 
CTRL-R is useful on hardcopy terminals after several 
corrections have been made to an input line. 

Papef/f/r is a uf/f/seful tb/b/ool (user types CTRL-R) 

Paper is a useful tool (line is retyped as the 

computer will see it. 
Input may continue at 
the end of the line.) 

U - cancels the current command line 

- S - stops the display of information on the terminal 
screen 

Q - continues printing output stopped with the 
CTRL/S on the terminal screen 

- suppresses output to the terminal screen but 
allows program to continue. Entering another CTRL-0 
reverses the effect so the output can be seen again. 
(The information output by the program while output 
to the terminal screen is suppressed is never seen 
by the user.) 



MOTE: Sometimes a terminal will not respond to a 
user, and appears to have stopped working. Often, 
this is because the user accidentally entered a 
CTRL-S or a CTRL-O. The terminal will usually 
respond if a CTRL-Q or CTRL-0 is entered. If that 
fails, enter a CTRL-Y. 
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2.3 DCL COMMAND FORMAT 

Any valid DCL command can be input by the user when the $ 
prompt is seen. The general format of all DCL commands is 
the same. However , some commands may be more explicitly 
defined or modified through the use of command options, 
parameters and qualifiers. 

Table 2-1 lists the major command formats and examples of 
commands using those formats. 

Table 2-1 



Command Format 



Example 



$command 
$command option 
$command option/qualifier 
$command parameter 
$command/qualif ier parameter 
$command parameter/qualifier 
$command parameter , parameter 
$command param,param/qualif 



$LOGOUT 
$SHOW SYSTEM 
$SHOW DEVICE/ALL 
$TYPE FILE. DAT 
$DIRECTORY/FULL FILE. DAT 
$PRINT FILE.DAT/C0PIES=2 
$PRINT FILE. DAT, TEST. FOR 
$PRINT A.DAT,B.F0R/C0PIES=4 



The first four characters of any DCL command, option, or 
qualifier uniquely identifies it to the DCL interpreter. 
For example, PRINT can be shortened to PRIN, and DIRECTORY 
can be shortened to DIRE. Many commands are uniquely 
defined by fewer characters than four, so the user rarely 
needs to enter the entire command. For example, DIRECTORY 
can actually be shortened to DIR. 

Many commands require an option or parameter so the DCL 
interpreter will know exactly what to do. The interpreter 
will prompt the user for missing information. For example, 
the PRINT command prompts for a file name. 



$PRINT 
$ file: 



(user pressed <RETURN> ) 
(system prompt . . .user 
should input file name) 
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As soon as the DCL interpreter has received all required 
information, it will invoke the corresponding system 
program. For example, the PRINT command requires only one 
file name. If a user enters one file name and presses the 
carriage return, the file will be printed. If the user 
intends to enter more than one file name, the carriage 
return should not be pressed until all file names have been 
entered. For example: 

$PRINT (user pressed <RETURN>) 

$_file: FILE. DAT (user enters file name and presses 

<RETURN>. File is printed) 

$PRINT 

$_file: FILE. DAT, A. DAT, B. DAT (user list names and does not 

press <RETURN> until all have 
been listed. All files are 
printed.) 

If a user needs to print so many files that the end of the 
line is reached before all files have been listed, a 
continuation marker can be placed at the end of the line. 
The continuation marker accepted by the DCL interpreter is - 
(a hyphen). The user can press the carriage return after 
entering the hyphen, and continue to input file names after 
the $_ prompt on the next line. A carriage return pressed 
after the last name causes all listed files to be printed. 
The continuation marker can be used with any DCL command. 
For example: 

$PRINT FILE. DAT, A. DAT, B. DAT, - 
$ TEST. FOR, PAYROLL. DAT 
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2.4 GETTING HELP 

All commands listed in Table 2-1 are valid DCL commands. 

More information is available on-line for every DCL command. 

To obtain this information, enter the command HELP when the 
$ prompt is seen. 

An alphabetical listing of all DCL commands and other 
selected topics will be seen. The HELP program then prompts 
for a topic. The name of any topic listed can be input 
after the prompt. Information about the topic will be 
output, including a statement "additional information 
available" preceding a list of subtopics, and a prompt for a 
subtopic. 

Information about a subtopic listed can be obtained by 
inputting its name. If a carriage return is entered 
instead, the topic prompt will be output. If another 
carriage return is entered, the user will see the $ prompt. 
For example: 

$HELP 

(Alphabetical list of commands and topics) 

Topic? PRINT (user enters name of topic) 

(general information about topic) 
(subtopics listed if available) 

Subtopic? /COPIES (user enters name of subtopic) 

(information about subtopic is output) 
Subtopic? (user presses <RETURN> ) 

Topic? (user presses <RETURN> ) 

$ 
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NOTES: 

1. The three words: options, parameters, and/or qualifiers 
are usually included in the list of subtopics for 
commands. Any of these may be entered as a subtopic to 
obtain general information. For example: 

Subtopic? parameters 

2. If the subtopic is a command qualifier, the / is part of 
the name of the qualifier, as seen with /COPIES. 

3. Another way to exit from the HELP program is by 
inputting a CTRL-C or CTRL-Y. 

4. The HELP command accepts a topic and/or subtopic as part 
of the HELP command to obtain information more quickly. 
For example: 

$HELP topic subtopic 

Some examples of this include: 

$HELP SHOW SYSTEM 
$HELP DIRECTORY 
$HELP PRINT/COPIES 
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2.5 OBTAINING INFORMATION ABOUT THE ENVIRONMENT 

The environment of a user is defined by the hardware on the 
system, the software available, and the information recorded 
about the user in the UAF. 

Users can look at their environment through the use of one 
or more DCL commands listed in Table 2-2. Use HELP to find 
out more information about these commands. 



Table 2-2 Commands to obtain information about environment 
Information desired Command to use 



List of all processes on system 

Information about own process 

Current statistics on own process 

♦Current position (device and 

directory) 

Current system date and time 

Characteristics of own terminal 

Characteristics of other devices 



$SHOW SYSTEM 
$SHOW PROCESS/ALL 
$SHOW STATUS 
$SHOW DEFAULT 

$SHOW TIME 
$SHOW TERMINAL 
$SHOW DEVICE 



♦discussed in Chapter 3 of this document. 
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2.6 MODIFYING THE ENVIRONMENT 

Users can change some of the characteristics of their 
environment. Table 2-3 lists the commands used to change 
typically modified characteristics. Use HELP to obtain more 
information about these commands. 



Table 2-3 Commands used to modify user environment 
Characteristic Command 



Password 

Width of line on terminal 



♦Default position 
(device and directory) 



$SET PASSWORD 

$SET TERMINAL/WIDTH=132 
$SET TERMINAL/WIDTH=80 

$SET DEFAULT [directory-name] 



♦discussed in Chapter 3 of this document 
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3.1 FILE CONCEPTS 

The following analogy should help you understand how 
information is stored and accessed on VAX/VMS. 

A large company, called WERGRATE, owns a building. The 
building is divided into many rooms. Some of these rooms 
are set aside for the storage of information. Filing 
cabinets line the walls of each of these storage rooms. 
File folders containing information are stored in most of 
the cabinets. 

In this analogy, we have defined several places: 

The building 

Rooms in the building 

Filing cabinets in each room 

One or more file folders in the cabinet 



Many different types of information can be stored in the 
file folders, such as drawings, reports, and personnel 
records. 

Many different kinds of files can be stored on a computer 
system. A file stored on a computer system can contain such 
things as text, source code, object code, or executable 
code. Files are created by an editor, a compiler, the 
linker, or other utilities. Normally, a file is stored on a 
disk or magnetic tape. 

The storage areas in a company correspond to storage areas 
in a computer system as seen in Table 3-1. 
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Table 3-1 Correspondence between a company and a VAX system 

A company A VAX system 

The building A node 

A room A device 

A filing cabinet A directory 

A file folder A file 



To send a person to retrieve a certain file folder, 
directions to the folder must be specified. The person must 
know which building to enter, where the correct room is, and 
which filing cabinet to open to access the folder. It is 
assumed the person sent is familiar with buildings, rooms, 
file cabinets, and folders. However, if the person is given 
incorrect directions, the folder may not be found, or a 
different folder may be retrieved. 

To send the computer system to access a file, directions to 
the file, called a file specification, must be given to the 
system. In VAX/VMS, a file specification includes the names 
of the node, device, directory, and file. The system is 
familiar with nodes, devices, directories, and file names, 
and will attempt to locate the file as specified. If the 
user gives the system an incorrect file specification, the 
system may respond with an error message, or by retrieving a 
different file than the user intended. 
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3.2 SPECIFYING FILES 

A file specification has the following format: 

Node: :Device: [Directory] File_name.File_type ;Version_number 

The fields of a file specification are discussed below. 

o Node:: - the name of the system connected to the device 
where the file resides. 

o Device: - the name of the device containing the volume 
(disk pack, magnetic tape) where the file is stored. 
Several devices may be connected to the user's system. 
Volumes can be moved from device to device. The 
information stored on a volume can be accessed only by 
specifying the name of the device where the volume is 
currently mounted. The system will respond with an 
error message if the volume is not available. 

o [Directory] - the name of a special file, a directory 
file, where the name of the file is listed. The 
directory file is stored on the same volume as the file. 
Directory files are discussed further in section 3.2.2. 

o File_name - any name chosen by the user. The name 
usually corresponds to the contents of the file. 

o .File type - should indicate the kind of information 
stored" in the file, such as text (.TXT), data (.DAT), 
FORTRAN source code (.FOR), object code (.OBJ). The 
file type may also be chosen by the user, and does not 
have to correspond to the contents of the file. 

o ;Version_number - indicates whether this is the first, 
second, third, etc. version of the file. When a file 
is created, the system assigns it a version number of 1. 
If the file is modified, the modified version is 
assigned the version number of 2. Each new modification 
is assigned a new number (increment is 1) . 
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For example : 

If the node is NODEA , 

the device is DRA3 , 

the directory is WHITE , 

the filename is MYFILE , 

the filetype is TXT , 

and the version number is 4 , 

then the full VMS file specification is: 

NODEA: :DRA3: [WHITE] MYFILE. TXT; 4 



The following are other examples of complete file 
specifications : 

ENGNDE: :DRA0: [BROWN] TESTFIL.DAT; 2 

DEPT01: :DBB3: [SERGIO] DRAWING 4. TXT; 33 

ACCTNG: :DBA1: [MANAGER] BUDGET. FOR; 1 

ACCTNG: :DRA0: [SYSEXE] HELP. EXE; 1 
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3.2.1 FILE SPECIFICATION RULES 

A few rules must be followed when creating a file 
specification: 

1. The punctuation marks are required to separate the 
fields of the file specification. 

2. Spaces are not allowed within a file specification. 

3. The name chosen for each portion (except the 
version number) may contain digits or characters, 
but must begin with a character. 

4. Each portion of the file specification is limited 
to a certain length: 

o Node: 1-6 characters 

o Device: 1-15 characters 

o Directory: 1-9 characters 

o File_name: 1-9 characters 

o File_type: 0-3 characters 

o Version number: 1-5 digits 
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3.2.2 DIRECTORIES AND SUBDIRECTORIES 

A directory file is a special kind of file. Directory 
files contain a list of names of other files. They are 
used by the system to access the other files. 
Directories reside on disk volumes. Normally, one 
directory file is created for each user on a system. 
The name of this file is often the same as the user's 
last name. 

A master directory file, named 000000. DIR, resides on 
each volume. This master file contains a list of the 
names of the top-level directory files on the volume 
(usually the files whose names correspond to user 
names) . 

For example, a volume could contain the directory files 
for BROWN, SMITH, BLACK, and JONES. When the 
000000. DIR directory file is listed, all of these names 
are seen: 

$DIRECTORY NODEA: :DRA1 :[ 000000] 

BLACK. DIR;1 BROWN. DIR;1 JONES. DIR;1 SMITH. DIR;1 

Several conclusions can be drawn from this example: 

1. Even though the name of the master directory is 
000000. DIR, to specify the name of the directory in 
the command, the syntax [000000] must be used. 
This is true of all directory files. Their names 
are in the form name. DIR, but they must be 
specified as [name] in a file specification. 

2. The DIRECTORY command always outputs file names in 
alphabetical order. 

3. Directory files are always version 1. 

The 000000. DIR file is a list of files which are 
directory files themselves. Each of these directory 
files should contain a list of files, some of which 
could be directories. The directories listed in the 
master file are called top-level directories. The 
directories listed in top-level directories are called 
subdirectories. Subdirectories are directory files 
which contain a list of file names, some of which can 
be directories. Directories listed in a subdirectory 
are also called subdirectories. 
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Directory files and subdirectories can be better 

understood through the use of a tree diagram (like a 
family tree), as seen in Figure 3-1. 



NODEA 
I 

I 



DRA0 DRA1 DRA2 

I I I 

000000. DIR;1 000000. DIR;1 000000. DIR;1 



I 



III I 

BLACK. DIR;1 BR0WN.DIR;3 J0NES.DIR;5 SMITH. DIR; 41 



I I I 

PR0JECT1.DIR;1 FILE.DAT;10 TEST.F0R;4 

I 



I I I 

SHIPSPD.BAS;2 DATA. DAT; 6 PROJNOTES. DIR; 7 



NOTESDATA.DAT; 3 SHIPNOTES. DAT; 9 
Figure 3-1 



In this figure, the files listed reside on the volume 
mounted in the disk drive, DRA1. The DRA1 device, as 
well as the DRA0 and DRA2 devices are connected to the 
system with the node name NODEA. Each volume contains 
a master directory. 

The master directory on the volume mounted in the DRA1 
device contains four top-level directories: BLACK. DIR, 
BROWN. DIR, JONES. DIR, and SMITH. DIR. The SMITH. DIR 
directory file (shown in figure) contains one directory 
file, PR0JECT1.DIR. PR0JECT1.DIR, a subdirectory of 
SMITH. DIR, contains a directory file, PROJNOTES. DIR. 
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Notice that directories also contain other kinds of 
files. 

The number of directory files which may be listed in 
any directory file is not limited. Therefore, 
SMITH. DIR could contain the names of more than one 
subdirectory, and each subdirectory file could contain 
the names of several other subdirectory files. 
However, only seven levels of directories may be 
defined from the top. (SMITH. DIR is a top-level or 
first-level directory. PR0JECT1.DIR is a second-level 
directory. PROJNOTES.DIR is a third-level directory.) 

3.2.3 PURPOSE OF DIRECTORIES AND SUBDIRECTORIES 

The major reason directories and subdirectories are 
created is to logically separate information on a 
volume. When users are separated from each other 
through the use of top-level directories, each user 
appears to own a portion of the volume for storage of 
information. VMS supports a protection scheme which 
can be used to prevent other users from accessing 
files. This protection can be used to protect an 
entire directory from access, or to protect only a few 
of the files in the directory. 

In some situations, one user could be working on 
several projects, each requiring several files. 
Subdirectories can be used to separate the files 
belonging to one project from files belonging to 
another . 

Subdirectories become very useful for a frequent user 
because directory listings can be very long. OpWhen 
information is separated, each directory is smaller and 
easier to work with. Any user can create a 
subdirectory with their own directory structure with 
the CREATE/DIRECTORY [name] DCL command. 



FILE NAMING AND MANIPULATING Page 3-9 

3.2.4 SPECIFYING FILES IN SUBDIRECTORIES 

The system assumes that a master directory is stored on 
each volume. When a file specification is input, the 
system searches the master directory for the directory 
name input. If the directory name is listed in the 
master file, the system searches the directory file for 
the file_name. 

If a file is stored in a subdirectory, the file_name is 
not listed in the top-level directory file; rather, it 
is listed in the subdirectory file. Therefore, the 
system must be given the name of the subdirectory file 
to search. In a file specification, this is done in 
the [DIRECTORY] portion by specifying the top-level 
directory name followed by a period. After the period, 
the subdirectory name is specified. If the file_name 
is listed in a second-level subdirectory, " the 
[DIRECTORY] portion will contain two names. For 
example, to specify DATA. DAT in the subdirectory 
PR0JECT1.DIR (see Figure 3-1), the following file 
specification can be used: 

NODEA: :DRA1: [SMITH.PR0JECT1JDATA.DAT 

If the file_name is listed in a third-level 
subdirectory, the top-level name and the second-level 
name must be specified first to provide a search path 
for the system. For example, to specify N0TESDATA.DAT 
in the subdirectory PROJNOTES.DIR (see Figure 3-1), the 
following specification can be used: 

NODEA: :DRA1: [SMITH. PR0JECT1. PROJNOTES] NOTESDATA. DAT 
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3.2.5 DEFAULTS 

Most users never have to input the complete file 
specification to uniquely identify a file to the 
system. This is because the system supplies several 
fields of the specification if the user does not 
specify them. These supplied fields are called 
defaults. The system stores some default values as 
part of the user's process. It is possible to default 
any field of the specification except the file_name. 
However, fields may be defaulted only under certain 
conditions: 

o The node (the name of the system) may be defaulted 
if the file resides on a device attached to the 
system where the user is currently working. 

o The name of one device where the user's top-level 
directory file is stored is recorded in the UAF for 
that user. If a device is not included in the 
specification, the name of this device (the 
default) is supplied. 

o The name of the user's top-level directory is 
normally recorded in the UAF. The system supplies 
this directory name if the user does not specify a 
directory. 

o The name of each file is unique, so the user must 
always supply a file_name. The system does not 
supply a default. 

o The kind of information stored in each file should 
be indicated by the file_type. Users may choose 
any file_type desired, but if the standard 
file types are used, certain system programs will 
suppTy the file_type field of the specification. 
For example, the PRINT and TYPE programs will 
always supply the file_type of LIS. However, if 
the user desires to print a file of type FOR, the 
file_type of FOR should be included in the file 
specification. 

Some system programs which accept input files and 
produce output files will assume one file_type for 
files input to them, and supply a different 
file_type for the output files. For example, the 
FORTRAN compiler assumes input files have the 
file_type of FOR, and supplies the OBJ file_type 
for files output. 
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The version number, as previously stated, is set to 
1 by default when the file is created. As modified 
versions are created, each is given a new version 
number. Version numbers are incremented by 1 
automatically. A user may assign any version 
number to a file or allow the system to assign 
numbers. System programs choose the version with 
the highest number by default if no number is 
given. 



Defaulting can be seen in the following example: 

Joe Brown is working 

on a system whose name is NODEA, 

where his files are stored on a device named DRA0 

in the top-level directory, [BROWN] . 
He is working with a file, TESTPRGM, 

whose file type is LIS. 
This is the third version of the file, and the other two 

versions are also residing in the [BROWN] directory. 



The program invoked by the PRINT command assumes all 
files input are of the type LIS. To print the file, 
Joe Brown can use any of the following commands: 

$ PRINT NODEA: :DRA0: [BROWN] TESTPRGM. LIS; 3 

$ PRINT DRA0: [BROWN] TESTPRGM. LIS; 3 

$ PRINT [BROWN] TESTPRGM. LIS; 3 

$ PRINT TESTPRGM. LIS; 3 

$ PRINT TESTPRGM. LIS 

$ PRINT TESTPRGM 
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3.2.6 CHANGING DEFAULTS 

Users can change the defaults recorded in their 
process. The SET NODE command is used to change the 
default node name to access another system connected by 
DECnet to the current system. The SET DEFAULT command 
can be used to change either the device name and/or the 
directory name. The new device name must correspond to 
an actual device on the system, and the new directory 
name must correspond to an existing directory. 

For example, the device and directory names recorded in 
the UAF entry for Joe Smith are DRA0 and [SMITH] , 
respectively (see Figure 3-1). When Joe logs in, the 
system sets his default to DRA0: [SMITH] . To compile 
DRA0: [SMITH] TEST. F0R;4, Joe only has to enter the 
command : 

$ FORTRAN TEST 

If Joe wants to print DATA. DAT in the subdirectory 
PR0JECT1.DIR (see Figure 3-1), the following command 
can be entered : 

$PRINT [SMITH.PR0JECT11DATA.DAT 

If Joe wants to work with several files for a while in 
that subdirectory, he could change his default: 

$SET DEFAULT [SMITH. PROJECT 1] 

$PRINT DATA. DAT 

Notice that Joe only has to enter the file_name and 
file_type after the default has been changed, since the 
default directory name is now [SMITH. PR0JECT1] . 

To change the default directory name back to [SMITH] , 
the following command can be used: 

$SET DEFAULT [SMITH] 

$PRINT [SMITH.PR0JECT1JDATA.DAT 

$ PR I NT DATA. DAT 
error message 

Notice that if Joe tries to print DATA. DAT now, the 
complete directory specification must be given, or an 
error message results. 



FILE NAMING AND MANIPULATING Page 3-13 

3.2.7 WILDCARDS 

To list the names of all files in a directory, the 
DIRECTORY command is used: 

$DIRECTORY [SMITH] 

To list the names of all files whose type is FOR in a 
directory, a wildcard, *, may be used instead of any 
particular file_name: 

$DIRECTORY [SMITH]*. FOR 

To list the names of all files whose names begin with G 
in a directory, the wildcard may also be used: 

$DIRECTORY [SMITH] G*.* 

To list all versions of a file: 
$DIRECTORY [SMITH] FILE. DAT;* 

This wildcard may be used in the directory, file_name, 
file type, and version number portions of the file 
specTf ication. The purpose of the wildcard is to save 
time and effort on the part of the user. 

Another useful wildcard is the period (.). The period 
is used within the [DIRECTORY] portion of the file 
specification: 

$DIRECTORY [SMITH. PR0JECT1] 

$DIRECTORY [.PR0JECT1] 

By using the period, the user did not have to enter the 
name SMITH. The system takes the current default value 
for the directory name, and includes it before the 
period. Then, the completed file specification is used 
to search for the requested file. 
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Therefore, if the default value is [SMITH. PR0JECT1] , 
the files in the subdirectory PROJNOTES, can be listed 
using : 

$DIRECTORY [SMITH. PR0JECT1. PROJNOTES] 

or 

$DIRECTORY [ . PROJNOTES ] 

Two other wildcards may be used with the directory 
portion as well; the ellipsis (...), and the hyphen 
(-) . The meaning of the ellipsis is to search down 
through the directory structure. So, to list all files 
in the current directory and all subdirectories: 

$DIRECTORY [...] 

The hyphen is used to mean back up one directory level. 
So, if the default is set to [SMITH. PRO JECT1 ] , and the 
user wanted to list the files in [SMITH] : 

$DIRECTORY [-] 

Wildcards may be used in conjunction with directory 
names. So, to list the files in the PR0JECT1 
subdirectory and all files below it (assuming the 
default directory is [SMITH]): 

$DIRECTORY [ . PR0JECT1. . . ] 

If the default is set to [SMITH. PR0JECT1] , and the user 
wanted to list all files in [SMITH] and all files in 
the rest of the structure: 

$DIRECTORY [-...] 

Other combinations may be used. Users should practice 
wildcards with the DIRECTORY command, as this command 
does not change anything. However, the wildcards are 
valid for use within most DCL commands requiring file 
specifications as parameters. 
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3.3 DECIPHERING ERROR MESSAGES 

When a problem occurs in a program, utility, or DCL command, 
an error message is displayed. The error message contains 
four parts and appears in the following format: 

%FACILITY-L-IDENT,TEXT 

%FACILITY is the name of the system program or utility that 
generated this error message (for example, DCL). 

L is the level of the error. There are five levels of 
errors: 

o S - Successful. No error is reported. Usually, no 
message is output if a program is successful. 

o I - Informational. No error, but the program outputs 
some information needed by the user. Often, these types 
of messages do not appear in the above format. 
Informational messages usually consist of text only. 

o W - Warning. The program may have completed 

successfully, or there may have been an error. The user 

should check to see if the desired task has been 
completed. 

o E - Error. The program has encountered an error. The 
program outputs the message and attempts to continue if 
possible. 

o F - Fatal or severe error. The program is not able to 
recover from this error and continue. The program is 
aborted. 

IDENT is a code word that is an abbreviation of the message 
text. 

TEXT is a descriptive message that tells the user what the 
problem is. 
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The following example shows the error message which results 
when a command unknown to the DCL interpreter is entered 
after the $ prompt. 

$SDDD 

%DCL-W-I WERB , unrecogni zed command 
\SDDD\ 

$ 

The error message is a warning, output by the DCL 

interpreter. The incorrect command is also echoed. (Most 

messages include the echoing of incorrect input in some 
format; not always enclosed in backslashes.) 

Some errors are detected by more than one utility, so 
several messages may be output. Usually, the first message 
contains the most pertinent information, but the others can 
be helpful. 

For example: 

$PRINT FILE. DAT 

%PRINT-W-OPENIN, error opening DRA0: [BROWN] FILE. DAT as input 

-RMS-E-FNF, file not found 

In this example, the file to be printed could not be found 
by RMS, so the PRINT program could not open it to print it. 
To correct this error, the user should create the file or 
enter the name of an existing file. 

The user should ask the following questions when an error is 
received, because the problem is usually a common one: 

o Is every part of the command spelled correctly? 

o Does the command exist (is it a valid DCL command)? 

o Were the options, qualifiers, and/or parameters chosen 
from the list displayed for the command by the HELP 
program? 

o Was the command entered correctly (i.e., are the 
options, qualifiers, and parameters, if any, in the 
correct order)? 

o Is the user allowed to use the command? 

o Is the user trying to access a non-existent or 
restricted piece of hardware or software? 



CHAPTER 4 
CREATING AND MANIPULATING FILES 



4.1 CREATING FILES WITH EDT 

EDT is the DIGITAL standard editor for text files. Files 
containing text can be created and modified using the EDT 
editor. The following command is used to invoke the editor: 

$EDIT file_specif ication 

Usually, the file_name and file_type are sufficient for the 
file specification. If the user desires to create a file on 
a different device or in a different directory than the 
current default values specify, the device and directory 
portions of the file specification will have to be included. 

When a file is created, the file is assigned the version 
number of 1. If the editor is being used to modify an old 
file, the editor will open the file of the name given which 
has the highest version number. 

Some examples : 

$EDIT FILE. DAT (uses defaults) 

$EDIT DRA0: [SMITH] FILE. DAT; 1 (no defaults used 

except system name) 

To create a file in a subdirectory, the same kind of command 
is used: 

Method one : 

$SET DEFAULT DRA0: [SMITH. PR0JECT1] 
$EDIT DATA. DAT 

Method two: 

$EDIT DRA0: [SMITH. PROJECT 1] DATA. DAT 
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When the carriage return is pressed after the command is 
input, the editor is invoked. The EDT editor outputs a 
message and a prompt. The EDT prompt is an asterisk, *. 

The EDT editor is capable of being in one of two modes, line 
mode and character mode. The * signals the user that EDT is 
in line mode, and is ready to accept line mode commands. 
(Note: DCL commands can not be input after the * prompt.) 

One line mode command is CHANGE, (can be abbreviated to C) . 
When this command is input, the mode is changed to character 
mode. No prompt is output for character mode, and the 
editor will only accept character mode commands. (Note: 
Neither DCL commands nor EDT line mode commands are accepted 
when there is no prompt.) 

A Computer-Based course is available that will teach you how 
to use the features of EDT. Contact your system manager to 
see if this course is available on your system. 

4.1.1 EDT LINE MODE COMMANDS 

Since character mode is so easy to use on video 
terminals, most line mode commands are only used on 
hardcopy terminals. People working on video terminals 
will normally use the CHANGE (to enter character mode), 
EXIT, QUIT, and SUBSTITUTE line commands. 

In line mode, the EDT editor numbers each line so it 
can be identified. Line numbers begin at and the 
normal increment is 1. However, fractional numbers are 
used also. For example, if a line is inserted between 
lines 1 and 2, the new line is given the number of 1.5. 
When too many lines have been inserted, numbers are not 
assigned to the new lines. At this point, the user can 
enter the RESEQUENCE command to renumber the file in 
increments of 1 (or some other chosen increment) . 

To indicate a line in a line mode command, the number 
of the line should be specified. To indicate several 
lines, a range can be specified by entering the number 
of the first line, followed by a colon and the number 
of the last line. For example, to DELETE lines 2 
through 10 (inclusive), the range is specified as 2:10. 
To indicate the entire file, as often happens with the 
SUBSTITUTE command, the symbol %WH (or %WHOLE) can be 
entered (see Table 4-1 for an example) . 

All EDT line mode commands are terminated by the input 
of a carriage return. All commands can be abbreviated 
(see Table 4-1) except the QUIT command. 
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Table 4-1 lists a subset of line mode commands. The 
EDT editor has on-line HELP, so help can be obtained on 
each of the commands listed. 



Table 4-1 Subset of EDT line mode commands 
Command Function 



Example (s) 



CHANGE 
COPY 



To change to character mode 

To copy a line or a group of 
lines from one area of the 
file to BEFORE another line 
in the file 



♦CHANGE or *C 

*COPY 10 TO 100 
*C0 1:5 TO 8 



DELETE 



EXIT 



HELP 



INSERT 



Delete a line or group of 
lines 

Exit from the editor, saving 
all changes 

Obtain help on all line 
mode commands 

Add text to the file. Editor 
inserts BEFORE current position 
or BEFORE line number specified, 
No prompt is output while 
inserting. To return to the 
* prompt, press <CTRL-Z>. 



♦DELETE 10 
*D11:25 

♦EXIT or ♦EX 



♦HELP or ♦H 



♦INSERT 

new text 
<CTRL-Z> 
♦15 

other new text 
<CTRL-Z> 
* 



MOVE 



QUIT 



REPLACE 



Move a line or lines from one 
area of the file to BEFORE a 
line in another area 

Exit from the editor without 
saving any changes 

Delete a line or group of lines 
and enter Insert mode to add 
text 



♦MOVE 10 TO 5 
♦MO 3:4 TO 11 



♦QUIT 



♦REPLACE 10 or ^R10 
1 line deleted 
new text added 
<CTRL-Z> 



RESEQUENCE 



SUBSTITUTE 



Renumber all lines in the 
file in increments of 1 

Substitute a new piece of 
text for an old piece 



♦RESEQUENCE 
♦RES 

♦SUBSTITUTE/old/new/%WH 
♦S/text/newtext/10 : 20 
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4.1.2 EDT KEYPAD MODE COMMANDS 

Character mode in the EDT editor is easy to learn, fast 
to use, and powerful. No prompt is output, because all 
commands are based on the current position of the 
cursor (the flashing light on the screen) . 

In character mode, the user is always inserting. 
Whenever a character is entered from the main keyboard, 
it is echoed on the terminal and becomes part of the 
file. New lines are created by pressing the carriage 
return. Commands are entered by using the keypad to 
the right of the keyboard. Character mode commands are 
terminated when they are input. (A carriage return 
does not mean 'end of command' in character mode.) 

Each key on the keypad means something different to the 
editor. Figure 4-1 shows the layout of the keypads for 
the VT52 and VT100. The commands available on each 
terminal are similar, but the keypad layout is 
different. Most users cut out a copy of one of these 
diagrams to paste to the front of the appropriate 
terminal for reference. 

The easiest way to learn how to use character mode is 
by using it. The following list of character mode 
commands should be practiced on a practice file until 
the user is familiar with them. 
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MAJOR KEYS 

o GOLD - used in conjunction with other keys. 
Normally, the command associated with a key is the 
command listed at the top of the square 
corresponding to the key in Figure 4-1. To invoke 
the commands at the bottom of the square, press 
GOLD, and then press the key. For example, the DEL 
C key deletes a character. Pressing GOLD and the 
DEL C key will undelete a character. 

o HELP - will output a picture of Figure 4-1 for the 
current terminal and allow the user to obtain HELP 
for any of the keys on the keypad. 

o ADVANCE - When pressed, causes the cursor to be in 
advance mode (the default) . All commands used to 
move the cursor will move it in a forward 
direction, towards the end of the file. 

o BACKUP - When pressed, causes the cursor to be in 
backup mode. All commands used to move the cursor 
will move it in a backward direction, towards the 
beginning of the file. 
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Commands affected by ADVANCE or BACKUP 
o SECT - moves the cursor several lines at a time 
o LINE - moves the cursor one line at a time 
o WORD - moves the cursor one word at a time 
o CHAR - moves the cursor one character at a time 
o EOL - moves the cursor to the end of a line 

Commands not affected by ADVANCE or BACKUP 

o DEL CHAR - deletes the character at the cursor 
position 

(DELETE - not on the keypad, but on the regular 
keyboard, deletes one character to the left of the 
cursor as usual) 

o DEL WORD - deletes the word to the right of the 
cursor 

o DEL LINE - deletes the line to the right of the 
cursor (including the carriage return and line 
feed) 

Note that when the DEL CHAR, DEL WORD, and DEL LINE 
keys are used, the deleted text is saved in a temporary 
buffer so the user can UNDelete the text. This is 
useful in the case of an accident, where text is 
unintentionally deleted. It is also useful when the 
user wants the same line of text to be placed in 
several places in the file. The user can delete the 
line, undelete it, and then move to the other places, 
undeleting the line wherever it is needed. However, 
these buffers only hold one value (i.e., one line, one 
word, or one character) at a time. They are 
overwritten by newly deleted values. 

If the user would like to save several lines of text in 
a buffer, to be placed in another place or several 
places in the file, the CUT and PASTE keys should be 
used. To save the text, the user should position the 
cursor at the beginning of the text and press SELECT. 
Then, the user should position the cursor after the end 
of the text and press CUT. The selected text will be 
removed from the file and placed in a buffer. 
Therefore, the text is deleted. The user could stop 
here, or replace the text elsewhere in the file by 



CREATING AND MANIPULATING FILES 



Page 4-7 



moving the cursor to the desired position and pressing 
PASTE. The text will be inserted before the current 
position of the cursor when PASTE is pressed. (Note 
that the GOLD key must be pressed before the PASTE key 
to enter the PASTE command.) 



EDT VERSION 

CTRL/A 

CTRL/O 

CTRUE 

CTRL/K 

CTRL/T 

CTRL/U 

CTRL/W 

CTRL/Z 

DEL 

BACKSP 

LF 



3 KEYPAD FOR VT100 
Comput* tab level 
DtcreaM tab tawl 
Ineraaae tabknl 



Delate to trart of 

tin* 

Refieeh kmhi 

Exit to EDT command 
Rubout character 

Goto baginningof 

HrM 

Delete to ttartot 

word 



VT100 KEYPAD 



ff 

1 1 


1 1 
1 1 


<— 


— > 



GOLD 


HELP 


FNDNXT 
FIND 


DEL L 
UNDL 


PAGE 
COMMAND 


SECT 
FILL 


APPEND 
REPL 


DELW 
UNDW 


ADVANCE 

BOTTOM 


BACKUP 
TOP 


CUT 

PASTE 


DELC 
UNDC 


WORD 
CHNGCASE 


EOL 
DEL EOL 


CHAR 
SPECINS 


ENTER 
SUBS 


LINE 
OPEN LINE 


SELECT 
RESET 




PF1 


PF2 


PF3 


PF4 


7 


B 


9 


- 


4 


5 


6 




1 


2 


3 


ENTER 
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DEL Delete elwecter 





Of word 


BACKSP 


Move to taginning of 
line 


CTRL/A 


Compute ttb level 


CTRL/D 


Dsotmw tab rtVtl 


CTRL/E 


.ncreeae tab level 


CTRL/F 


Fill text 


CTRL/K 


Define key 


CTRL/T 


Adjust tab* 


CTRL/2 


Return to line mode 


VT 52 KEYPAD 



GOLD 


HELP 


DELL 
UNDL 


UP 
AEPLACE 


PAGE 
COMMAND 


FNDNXT 
FIND 


DELW 
UNDW 


DOWN 
SECT 


ADVANCE 
BOTTOM 


BACKUP 
TOP 


DELC 
UNDC 


RIGHT 
SPECINS 


WORD 
CHNGCASE 


EOL 
DEL EOL 


CUT 
PASTE 


LEFT 
APPEND 


LINE 
OPEN LINE 


SELECT 
RESET 


ENTER 
SUBS 




BLUE 


RED 


GRAY 


ft 


7 


8 


• 


U 


4 


S 


6 


— > 


1 


2 


3 


< — 





• 


ENTER 



Other EDT character mode commands are used less 
frequently. Information about them can be obtained 
through the HELP facility. 
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4.1.3 RECOVERING FROM A SYSTEM FAILURE 

Recovering from a system failure during an edit session 
is not difficult with the EDT editor. While the user 
is editing, EDT is creating a journal file. This 
journal file contains a list of all commands entered 
since the beginning of the session. After the system 
is running again, users can recover all edits done by 
using the command: 

$EDIT/RECOVER f ile_specif ication 

The user should specify the name of the file which was 
being edited at the time of the system crash. The EDT 
editor will read the latest version of that file as 
input, and use the commands listed in the journal file 
of the same name ( name.JOU) to reconstruct the work 
done. During recovery, the editor will actually repeat 
the work done previously by the user. Users should not 
touch the keyboard until the editor is done and a 
prompt (if they were in line mode) appears. If the 
system crashed while the user was in character mode, 
the user should wait until the cursor stops moving 
around. After the editor completes the journal file's 
list of commands, it will accept commands from the 
user. (Note: A journal file will also be created if 
the user exits the editor incorrectly (i.e. with a 
CTRL-Y) . ) 
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4.2 FILE MANIPULATION WITH DCL COMMANDS 

Several DCL commands are useful for moving, copying, 

printing, and obtaining information about files. Table 4-2 

contains the most commonly used DCL commands for these 
purposes. 

The * wildcard can be used with any of these commands in 
place of one or more fields of the file specification. 
Notice that most commands will prompt for missing 
information. This is especially useful for the COPY 
command, as shown. 

More information about any of the commands in Table 4-2 can 
be obtained through the use of the HELP command. 
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Table 4-2 Commonly used DCL commands for file manipulation 
Command Function Example 



DIRECTORY 



COPY 



RENAME 



PRINT 



TYPE 



DELETE 



PURGE 



Used to obtain information about 
files. The /FULL qualifier is 
used to obtain more information. 

Used to copy information stored 
in one file to another file. 
The second file usually has a 
different file specification. 
(Result is two files 
containing the same information) 

Used to change the name of a 
file. 



For printing a file on the 
system default printer 
designated by the system manager 

For outputting the contents of 
a file to the terminal. 



To delete a file, 
version number. 



Requires a 



To delete all but the latest 
version of any or all files 
in a directory. 



$DIRECTORY 
$DIRECTORY/FULL 



$COPY 

$_from: FILE. TXT 

$ to: DATA. DAT 



$RENAME 

$_f rom : DATA . DAT 

$_to: TEST. FOR 

$PRINT BUDGET. FOR 



$TYPE FILE.BAS 

$DELETE NAME. DAT; 3 

$ PURGE 

$PURGE FILE. DAT 



CHAPTER 5 
PROGRAM DEVELOPMENT 

5.0 INTRODUCTION TO PROGRAM DEVELOPMENT 

VAX/VMS provides a number of tools that significantly 
decrease the time spent developing VAX-11 programs. These 
tools include: 

o Interactive Text Editor (EDT) 

o Programming Languages 

o Linker 

o Librarian 

o Common Run-Time Library 

o Symbolic Debugger 

o Record Management Services 

The editors, programming languages, and linker, are 
utilities that are used to prepare a source program for 
execution. The symbolic debugger is used to detect errors 
in executable programs (programs that do not appear to 
contain errors when compiled/assembled and linked, but, 
nevertheless, fail to produce correct results). 

The librarian enables storage of frequently-used segments of 
code, such as procedures or functions, in specially indexed 
files called libraries. Procedures or functions stored in a 
library can be referenced in a program. The linker combines 
the code from the library with the user's source code to 
produce an executable image. 
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For the MACRO language, definitions (macros) can be stored 
in a different type of library. Libraries containing macros 
can be accessed by the assembler to include a specific macro 
in the program. 

The Run-Time Library is a system library containing a large 
number of predefined routines that can be called from user 
programs (such as routines to manipulate strings or generate 
random numbers) . The MACRO programmer will find some of the 
I/O routines to be especially useful, while high-level 
language programmers will probably use the math or bit 
manipulation routines more often. Help can be obtained 
on-line for most of the Run-Time Library routines by 
entering the DCL command, HELP RTL, and specifying one of 
the categories listed as the subtopic. 

This chapter begins with a discussion of program development 
in general, followed by sections on each of several VAX-11 
programming languages (MACRO, FORTRAN, PASCAL, BASIC, and 
COBOL) . Those sections contain a discussion of the VAX-11 
specific conventions regarding that language, a sample 
program, and a debug session using the sample program. 

5.1 PROGRAM DEVELOPMENT ON VAX/VMS 

To develop a program written in a programming language, the 
following sequence of steps must be completed: 

1. Create a text file with an editor which contains 
statements written in a programming language. 

2. Compile/Assemble the source program. 

3. Link the compiled program to create an executable image. 

4. Test the program. 

5. Debug (make corrections to) the source program and 
repeat steps 2 through 5 until the program executes 
properly. 

These steps are explained in detail on the following pages. 
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1. Create a text file which contains the source statements 
of your program. 

The file_type should be related to the language being 

used. Two reasons that this is important is that it 

helps you tell a source program in one language from 

another, and the compilers will search for certain 
default file_types as shown below. 

Language Default File_Type 

MACRO .MAR 

FORTRAN . FOR 

BASIC .BAS 

PASCAL . PAS 

PLI .PLI 

COBOL .COB 

The entire program may be entered in one text file, or 
several files may be created. Usually, if several files 
are created, the code representing the main program is 
entered in one file, and the subprograms referenced are 
each placed in separate files. There is no rule stating 
a limit on the number of subprograms per text file. 
However, if each is in a separate file, they are more 
accessible to other programs. 

2. Compile/assemble the text file to produce a file 
containing object code. 

The compiler/assembler translates the source statements 
of each input file into executable code, producing one 
or more object files of type .OBJ. 

To compile/assemble the code, the command related to the 
language must be used: 

Language Compiler/Assembler Command 

MACRO $MACRO file specification 

FORTRAN $FORTRAN f iTe_specif i cat ion 

BASIC $BASIC f ile_specif ication 

PASCAL $PASCAL file_specif ication 

PLI $PLI file specification 

COBOL $COB0L fiTe_specif ication 

File_types other than the defaults listed earlier must 
be included in the file specification. Otherwise, the 
appropriate file_type wilT be provided by the command 
used. 
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More than one input file may be listed as parameters. 
If input f ile_specif ications are separated by (,) 
commas, a separate object file is created for each input 
file. If they are separated by (+) plus signs, one 
object file is created containing the code from all 
input files. 

If syntax errors are found in the source code, an 
appropriate message will be output at the user's 
terminal . The DCL HELP command can be used to 
understand errors output by the compilers for FORTRAN, 
BASIC, and COBOL by entering HELP language ERROR. 

When the error is understood, an editor should be used 

to correct the source code, and the new version of the 

text file should be submitted to the compiler/assembler 
for translation. 

Many qualifiers can be used in conjunction with the 
compiler or assembler command. The DCL HELP command can 
be used to obtain information about qualifiers by 
entering the 'HELP language_name ' command. Most 
compilers will take the following qualifiers with the 
compile command. You should check the user guide for 
the specific language for information on other 
qualifiers. 



Qualifier 



Use 



/LIST 



/CROSS REFERENCE 



The most commonly used qualifier 
that causes a listing file to be 
produced as well as the object 
file. The file is useful when 
trying to debug the program. 

The cross reference qualifier 
tells the compiler to generate a 
cross reference listing. This 
type of list contains program 
symbols, their class, and the 
program lines in which they are 
referenced. 



/DEBUG 



The debug qualifier tells the 
compiler to provide information 
to the symbolic debugger and the 
system run-time error traceback 
mechanism. 
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For example, to compile a BASIC program, called SAMPLE, 
and obtain a list of the program as well as cross 
referenced listing of program variable you would type: 

BASIC/LIST/CROSS_REFERENCE SAMPLE 

3. Link the object file or files to produce an executable 
image . 

The linker assigns virtual addresses to the lines of 
executable code in each input file, and resolves 
references to symbols between modules. The linker also 
searches personal and system libraries for external 
procedures and functions that cannot be found in the 
input files specified. 

To link the object file(s), the VAX-11 Linker is invoked 
using the DCL command, LINK. The names of the files to 
be linked, such as object code files or modules from 
libraries, can be specified following the command. 
Names should be separated by commas. The linker assumes 
the file_type of input files is .OBJ. 

The file output by the linker contains executable code, 
and is assigned the file_type of .EXE. 

If the linker is unable to resolve certain symbols or to 
locate certain subprograms, it displays an appropriate 
error message. Linker errors usually indicate one of 
two problems : 

o A subprogram was referenced but not included in the 
list of input files 

o A subprogram/variable was not defined/referenced 
properly in the program 

Linker errors and recommended solutions are described in 
the VAX-11 Linker Reference Manual. 

Several qualifiers are available for use with the linker 
command (enter HELP LINK) . Cross-reference listings, 
maps, and other information can be written to files or 
to the terminal by using these qualifiers. The 
information produced is most useful to the more advanced 
programmer, and will not be discussed in this document. 
The following table shows some of the most common LINK 
command qualifiers. 
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Qualifier 
/MAP 

/CROSS REFERENCE 



Use 



/DEBUG 



This qualifier produces a file 
containing a list of the symbols 
and data used in the program and 
their locations in memory. 

This qualifier produces a cross 
reference list of each global 
symbol used in the program, its 
value, the name of the first 
module in which is defined, and 
the name of each module in which 
it is referenced. 

The qualifier causes the linker to 

(1) Generate a Debug Symbol Table 

(2) Gives control to the debugger 
when the image is run. 



The following example illustrates the use of the LINK 
command to create an executable image of the program 
SAMPLE and creating a map file. 



LINK/MAP SAMPLE 
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4. Test the image produced from the linker. 

To execute a program, enter the DCL command, RUN, 
followed by the name of a single executable image file. 
The run command assumes the file_type of the input file 
is .EXE. 

Users should not attempt to execute a program if 
compiler and linker errors have not been corrected. 

Errors output at run-time could indicate syntax problems 
not identified by the compiler/assembler or linker. 
Other run-time errors could be output by procedures 
referenced by the program, such as system routines. 
Some errors output by system routines are documented 
on-line. To look at a description of these errors, 
enter the DCL command, HELP ERROR, and enter the 
appropriate facility code as the subtopic. Information 
on other errors can be obtained by entering HELP ERROR 
SYSTEM error_code. 

If all obvious errors have been corrected, errors output 
at run-time can indicate logical errors. A logical 
error occurs because the organization of the statements 
in the program does not do the intended job. A logical 
error could produce error messages, or, simply, the 
wrong result. Results should be checked carefully. If 
the program receives input from the user, it should be 
executed several times with various types of input to be 
sure it does the required job in all given situations. 

To correct the program, the user must debug it to find 
out where the error is occurring. When the error is 
found, the source program must be modified and submitted 
to the compiler/assembler and linker again. Then the 
new executable file can be executed to see if the error 
was corrected. 
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5. Debug the program to correct errors. 

To find the cause of a logical error, the user must 
examine the program carefully, looking at the source 
code one line at a time. Lists of variables and their 
contents should be kept on paper, as well as comments on 
loops and output to peripherals. Often, in larger 
programs, the problem can be isolated to a particular 
area of the program, saving the user the time of looking 
at every line. 

If the problem can be isolated, or the program is not 
very large, examining a program using paper is not 
difficult, and errors can be easily found. As larger 
programs are written, involving more I/O and more 
variables and more loops, debugging becomes more 
complicated. 

The VAX-11 Symbolic Debugger is provided to simplify the 
user's debugging job. Symbolic debugger commands 
implement the same debugging techniques used on paper. 

The flowchart in Table 5-1 summarizes the program 
development steps. Although the flowchart in the table 
uses a FORTRAN program, the flowchart can be used for a 
program written in any programming language. 
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CREATE A 

SOURCE 

FILE 



COMPILE THE 
SOURCE FILE 



LINK THE 

OBJECT 

FILE 



RUN THE 

IMAGE 

FILE 




CORRECT THE 
SOURCE PROGRAM 




YES 




YES 



Developing a Program 
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5.2 LOGICAL NAMES 

If a file specification or device name is included in the 
source fTle for a program, the program is said to be file 
dependent or device dependent. When the program is 
dependent, the file or device must exist when the program is 
executed, and the program always outputs to or inputs from 
the file or device specified. 

Pile and device independence can be achieved through the use 
of logical names. A logical name is created by the DCL 
command ASSIGN, and can be used in a program instead of the 
file or device name. The ASSIGN command assigns a specified 
logical name to a specified device or file name (called the 
equivalence name) . When the logical name is encountered in 
a program, the system translates it into the equivalence 
name. The general forms of the DCL ASSIGN command are: 

ASSIGN device: logical name 

ASSIGN f ile_specif ication logical name 

The example below illustrates the use of the ASSIGN command 
to make a program device and file independent. 



PROGRAM 1 

File dependent program 

writes to particular file, 
FILE. DAT 



PROGRAM 2 

File independent program 

writes to logical name, 
OUTPUT FILE 



Execution of PR0GRAM1: 



Execution of PR0GRAM2: 



$RUN PROG RAMI 

$TYPE FILE. DAT 
contains output 
from 1st execution 

$RUN PROGRAM 1 

$TYPE FILE. DAT 
contains output 
from 2nd execution 



$ASSIGN GENERAL.DAT OUTPUT_FILE 
$RUN PROG RAM 2 
$TYPE GENERAL.DAT 

contains output from 

1st execution 
$ASSIGN OUTPUT.DAT OUTPUT_FILE 
$RUN PROG RAM 2 
$TYPE OUTPUT.DAT 

contains output from 

2nd execution 



Notice that PR0GRAM1 always outputs to FILE. DAT, whereas 
PR0GRAM2 can send output to a different file each time it is 
executed. (The assignment command must be executed prior to 
the execution of the program.) 
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Several logical names are provided by the system, and are 
stored in the user's process logical name table. To look at 
the table, use the DCL command SHOW LOGICAL/PROCESS. Table 
5-2 lists some of the system-defined logical names commonly 
used in programs. 



Table 5-2 System-defined logical names 
Logical name Equivalence name 



SYS $ INPUT 
SYS$OUTPUT 
SYS$DISK 
SYS$LOGIN 



Default input device. For the interactive 
user, SYS$INPUT is equated to the terminal. 

Default output device. For the interactive 
user, SYS$OUTPUT is equated to the terminal, 

Default user disk established at login time 
Can be changed by SET DEFAULT command. 

Default user disk and directory established 
at login time. Usually the top-level 
directory. Specified in the user's UAF 
entry by the system manager. 
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5.3 A SAMPLE PROGRAM — GRADES 

The GRADES program has been created in each language 
discussed in this chapter. The listing file for each 
language's implementation of GRADES is included in the 
section of the chapter discussing that language (following 
this section) . 

The GRADES program creates a file containing the names of 
students and the average of their grades for a particular 
course. The program obtains the names and grades from the 
user, computes the average of the grades, and outputs the 
results to the terminal and to a designated file. The 
logical name 'Course*, created before the program is 
executed, is assigned to the name of the output file. For 
example : 

$ASSIGN HISTORY.DAT Course 
$RUN GRADES 

In this example, the program GRADES is executed to compute 
the average of the grades for the students in the history 
class. The output file, HISTORY.DAT, is assigned to the 
logical name 'Course* before the program is executed. The 
program writes results to the logical name 'Course*. 
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5.3.1 NORMAL EXECUTION OF GRADES 

A sample run of the GRADES program follows 
FORTRAN version was used in this example: 

♦ASSIGN ENGLISH* DAT COURSE 
♦FORTRAN GRADES 
♦LINK GRADES 
♦RUN GRADES 



The 



Student name? JOHN SMITH 








Input grade (or to end 


input) ? 


45 




Input tirade (or to end 


input) ? 


80 




Input tirade (or to end 


input) ? 


99 




Input tirade (or to end 


input) 1 







Student? JOHN SMITH 






Average? 



74*7 



Are you done ? (Yes/No) N 

Student name? MARY HAGERTY 

Input grade (or to end input) J 82 

Input grade (or to end input)? 69 

Input grade (or to end input) J 94 

Input tirade (or to end input) J 



Student? MARY HAGERTY 
Are you done ? (Yes/No) N 
Student name? HOSIAH HOWER 



Input 
Input 
Input 
Input 



tirade 
grade 
tirade 
tirade 



(or 
(or 
( o r 
(or 



to 
to 
to 

to 



end 
end 
end 
end 



input) ? 
input) ? 
input) ? 
input) ? 



90 
78 
81 





Average? 



81,7 



Student? HOSIAH HOWER 

Are you done ? (Yes/No) Y 

♦ 

♦ 

•TYPE ENGLISH* DAT 

Student? JOHN SMITH 

Student? MARY HAGERTY 

Student? HOSIAH HOWER 



Average? 



83*0 



Avera.Se? 74*7 
Average? 81*7 
Average? 83*0 



PROGRAM DEVELOPMENT Page 5-14 

5.4 USING THE SYMBOLIC DEBUGGER 

Three methods are available for invoking the Symbolic 
Debugger : 

1. Including the debugger in the executable image. 

The debugger is included in the executable image if the 
/DEBUG qualifier is entered with the LINK command. When 
your program is subsequently executed, the debugger is 
automatically invoked, and the debug prompt is output. 
For example: 

$LINK/DEBUG filename 

Unless the /DEBUG qualifier is also included in the 
compiler command (/ENABLE=DEBUG with the MACRO command), 
local symbol tables will not be included. The symbol 
tables contain the names and addresses of various 
symbols and variables used in the program. If the user 
intends to examine the contents of variables, the tables 
should be included. Other debug commands, such as GO, 
STEP, or setting tracepoints, work without this 
information. 

2. Halting the program and invoking the debugger with the 
DCL command $DEBUG. 

A program can be halted by entering <CTRL/Y> or 
<CTRL/C>. The debugger can then be invoked by entering 
the DCL command, DEBUG. In this case, the debugger does 
not have access to local symbols. 

This method can be used to halt a 'hung' program, one 
that will not run to completion. The debugger can be 
used to determine where the program is hung. 

This method can also be used for a program that is 
executing in the debugger already in case the user wants 
to input a debug command at a time when the debug prompt 
is not seen. 

3. Running the program with the debugger. 

A program can be run with the debugger if the /DEBUG 
qualifier is included in the RUN command. Again, if the 
debug qualifier was not included with the 
compiler/assembler command, the symbol tables will not 
be included and the contents of variables can not be 
accessed. 
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Table 5-3 Major Symbolic Debugger Commands 

Feature Description Command Format 



Display 
values 

Change 
values 

Define 
symbols 

Calculate 
values 

Get help 

Breakpoints 

Tracepoints 

Watchpoints 



Test 
subroutines 

Execute 
program 



Debug 
routines 



Display variable contents 
using symbolic names 

Modify variable contents 



Define symbolic names 
for later use 

Compute expressions using 
symbolic names 

Get help for any command 

Suspend program execution 
at a specified point 

Monitor order of execution 
of program lines 

Suspend program execution 
when the content of a 
variable changes 

Call and pass arguments 
to a subroutine 

- from a given point 

- for a specified 
number (n) of 
instructions or lines 



EXAMINE variable 



DEPOSIT variable = 
value 

DEFINE symbol = 

value 

EVALUATE expression 



HELP [command_name] 
SET BREAK at line # 

SET TRACE at line # 

SET WATCH variable 

CALL sub_name 
[ (arg, ...)] 

GO [address] 

STEP [n] 



Make symbols from specified SET MODULE module 
module available to debugger 

Define default module name SET SCOPE module 

for setting tracepoints and 

watchpoints on symbols whose 

names appear in more than one 

module 



Stop 
debugger 



Leave debugger 

and return to DCL prompt 



EXIT 



Note: Fields enclosed in [] (brackets) are optional. 
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5.4.1 EXECUTION OF GRADES WITH THE DEBUGGER 

Three examples of the GRADES program using the debugger 
follow. The FORTRAN version of the program was used. 
The syntax of most of the debug commands shown is the 
same for other languages. Therefore, these debug 
examples and associated comments should be read by all 
users. A listing of the FORTRAN program is provided 
before the examples. 

Each of the languages mentioned earlier is discussed 
briefly in the sections following these examples. A 
listing of the GRADES program is included, followed by 
a discussion on using the symbolic debugger with that 
language . 

A brief description of most of the commands used can be 
found in Table 5-3. The HELP facility in the debugger 
can be used to obtain more information. More 
discussion of some of the commands and their output is 
included with the examples. 



PROGRAM DEVELOPMENT 



Page 5-17 



Listing of Main Program 



0001 




0002 




0003 




0004 




0005 




0006 




0007 




0008 


10 


0009 


20 


0010 




0011 


30 


0012 




0013 




0014 




0015 




0016 




0017 


40 


0018 




0019 




0020 


50 


0021 




0022 


60 


0023 




0024 




0025 




0026 





PROGRAM GRADES 

CHARACTER STUDENT_NAME*30» D0NE*4 
REAL AVERAGE 

OPEN (UNIT=1. FILE='Course'i STATUS='New' > 

TYPE 20 

FORMAT (/' Student name? '#♦) 
ACCEPT 30f STUDENT-NAME 
FORMAT <1A30) 

CALL Get-ssrades-conpute-averade (AVERAGE) 

TYPE 40.STUDENT_NAMEi AVERAGE 

WRITE (1.40) STUDENT-NAME. AVERAGE 

FORMAT (/' Student: ' »A30i 'Average! '»F10.1> 

TYPE 50 

FORMAT (/' Are you done ? (Yes/No) '»♦> 

ACCEPT 60i DONE 

FORMAT <1A4) 

IF (DONE.NE.'Y' .AND. DQNE.NE.'v') GOTO 10 

CLOSE (UNIT-1) 
END 



Listinfl of Subroutine 



0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
0020 
0021 
0022 
0023 



SUBROUTINE Get-* rade«-co»Pute_averaae (AVERAGE) 

INTEGER ICOUNT 
REAL TOTAL* GRADE 

ICOUNT - 

TOTAL ■ 

10 TYPE 20 

20 FORMAT (' Input «r»de (or to end input) J '.«) 

ACCEPT 30t GRADE 
30 FORMAT (F10.0) 

IF (GRADE. NE.O) THEN 

ICOUNT ■ ICOUNT + 1 

TOTAL - TOTAL + GRADE 

GO TO 10 
ENDIF 

40 IF (ICOUNT. NE.O) AVERAGE « TOTAL/ICOUNT 

RETURN 
END 



PROGRAM DEVELOPMENT Page 5-18 



EXAMPLE 1 — Setting watchpoints and breakpoints 



The following three DCL commands compile, link, and execute the 
program GRADES. Because the /DEBUG qualifier was used in the 
language compile and LINK command the symbolic debugger will 
gain control of the program execution. 

•FORTRAN/L I ST/DEBUG GRADE'S 
•LINK/DEBUG GRADES 
•RUN GRADES 

VAX-11 DEBUG Version 3,0-5 

ZDEBUG-I-INITIALf Lsnsfusge is FORTRAN? module set to "GRADES' 

The EXAMINE command of the debugger allows you to check the 
contents of variables in the program. The DEPOSIT command 
gives you the opportunity to alter the contents of variables. 
With the following debug commands the value of the variable 
DONE is examined and altered. The SET WATCH command sets 
a watchpoint on the variable which causes the debugger to 
display the old and new values of the variable whenever the 
contents of the variable is altered. The SHOW WATCH command 
causes the debugger to display the locations at which 
watchpoints have been established. 

DBG>EXAMINE DONE 

GRABES\D0NEU*4)J 

DBG>DEP0SIT D0NE= H YES H 

DB0>EX AMINE DONE 

GRADESXDONE < 1 * 4 > J YES 

DBG>SET WATCH DONE 

DBG>SH0W WATCH 

watchpoint at GRADES\D0NE(1*4) for 4, bytes ♦ 

The GO command causes the program to execute or resume execution 
at the point it was suspended. 

DBG>G0 

routine start at GRADES 

Student name? JOE SMITH 

Input grade (or to end input)* 6 

Input tirade (or to end input)* 7 

Input tirade (or to end input)* 

Student* JOE SMITH Average* 6.5 

Are you done ? (Yes/No) N 
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Because a watchpoint was established for the variable DONE the 
debugger displays the old and new contents of the variable. 



write to GRADES\DONE( 1 *4) 
old value ~ YES 
new value =•- N 
DB6>EX AMINE DONE 
GRADES\DONECI.M)* N 



at PC 7064? 



In the following section a breakpoint is set with the SET BREAK 
command at line 23. When the program resumes execution with the 
GO command the debugger will indicate the module name and the 
line number where the program is interrupted. 



70659 
GRADES\%LINE 23 



DBG>SET BREAK JSLINE 23 

DBG>G0 

start at 

break at 

DBG>60 

start at GRADES\%LINE 23 

Studen 

Input 

Input 

Input 



t name? GERALD HORNER 

stfrade (or to end input) J 50 

tirade (or to end input)* 1.00 

£rade (or to end input)? 



Student! GERALD HORNER 



Average 



75*0 



Are you done ? (Yes/No) N 

write to GRADES\D0NE(iJ4) at PC 70649 

old value ~ N 

new value = N 

The CANCEL WATCH command is used to cancel watchpoints that have 
been set. 



DBOCANCEL WATCH DONE 

DBG>G0 

start at 70659 

break at GRADES\%LINE 23 

DBG>G0 

start at GRADES\%LINE 23 

Student r.3me? MARY HAGERTY 

Input grade (or to end input)* 

Input grade (or to end input) J 

Input grade (or to end input)* 



9 
9 




Student* MARY HAGERTY 



Average 



9*0 



Are you done ? (Yes/No) N 

The CANCEL BREAK command cancels a single breakpoint or by using 
the /ALL qualifier cancels all breakpoints set in the program. 
Now that all watchpoints and breakpoints have been cancelled 
program execution will continue until normal program execution. 
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»BG>CANCEL BREAK/ALL 

DBO>00 

start at GRADES\%LINE 23 

Student name? HORACE 0' TOOLE 

Input grade (or to end input)? 8 

Input grade (or to end input)* 

Student? HORACE 0' TOOLE Average 8*0 

Are you done ? < Yes/No) N 

Student name? CRAIG SMYTHE 

Input grade (or to end input)* 10 

Input grade (or to end input)* 10 

Input grade (or to end input)* 

Student* CRAIG SMYTHE Average 10*0 

Are you done ? (Yes/No) Y 

The following message and command indicates normal program 
termination. Control is then returned to the debugger. The 
EXIT command terminates the debugger and returns control to 
DCL. 

Is '%SYSTEM-S~N0RMALr normal successful completion" 

DBOEXIT 

$ 
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EXAMPLE 2 — Setting tracepoints and single stepping 



Before you can use the symbolic debugger you must first compile 
the program with the /DEBUG qualifier, then link the program 
again using the /DEBUG qualifier. When you run the program the 
symbolic debugger will automatically take control of the 
execution of the program. 

*FORTRAN/LIST/DEBUG GRADES 
♦LINK/DEBUG GRADES 
*RUN GRADES 

YAX--11 DEBUG VERSION 3.0-5 

%DEBUG~- 1 -INITIAL? Lans-SuasSe is FORTRAN r module set to 'GRADES' 

The EXAMINE and DEPOSIT commands allow you to check the values of 
variables in a program and alter the contents of those variables. 
In this example the value of DONE was examined and its contents 
displayed. With the DEPOSIT command the variable DONE was 
altered to contain "YES". 

dbg>exam:i:ne done 
grades\d0necu4k 
dbodeposit done ="yes" 

A breakpoint is set at line 23 so that execution of the program 
will be interrupted. When the program is interrupted the debugger 
displays the DBG> prompt. Using the SET TRACE command tracepoints 
are set in the program. Tracepoints allow you to examine the order 
in which the statements are being executed. 

DBG>SET BREAK KLINE 23 

DBG>SET TRACE KLINE 8 

DBG>SET TRACE KLINE .1.3 

DBG>SET TRACE KLINE 19 

DBG>G0 

routine start at GRADES 

trace at GRADESXKLABEL 10 

Student name? JOE SMITH 

trace at GRADES\KLINE 13 

Input grade (or to end input)* 6 

Input grade (or to end input) J 7 

Input grade (or to end input)* 



Student? 
trace at 



JOE SMITH 
GRADESNKLINE 19 



Average* 



6 » 5 



Are you done ? (Yes/No) N 
break at GRADESNKLINE 23 
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While the GO command causes the program to execute until a 
breakpoint is reached or the program terminates normally, the 
STEP command causes the debugger to execute one single 
statement . 

BBG>STEP 

start 3t GRADESNJKLINE 23 

stepped to GRABES\%LABEL 10 

DBG>STEP 

start 3t GRADES\%LABEL 10 

trace at GRA0ES\%LABEL 10 

Student name? MARY HAGERTY 
trace at GRADES\%LINE 13 

Input grade (or to end input) J 100 
Input grade Cor to end input)* 50 
Input sirade (or to end .input) J 

Student? MARY HAGERTY Average? 75.0 

trace at GRABES\%LINE 19 

Are you done ? (Yes/No) N 
break at QRADESNXLINE 23 

The CANCEL TRACE command with the /ALL qualifier cancels all 
tracepoints set in the program. 

DBG>CANCEL TRACE/ALL 

DBQX30 

start at GRA»ES\%LINE 23 

Student name? CRAIG SMYTHE 

Input sir side (or to end input)! 9 

Input grade (or to end input)* 9 

Input grade (or to end input)* 

Student? CRAIG SMYTHE Average? 9.0 

Are you done ? (Yes/No) Y 

Because the breakpoint is still set for line 23 the debugger 
continues to halt execution. 

break at GRADES\%LINE 23 

DBG>00 

start at GRA»ES\%LINE 23 

Is / %SYSTEM~S-NGRMAL» normal successful completion' 

BBG>EXIT 
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EXAMPLE 3 — Complex debug session of GRADES 

SFQRTRAN/DEBUG/LIST GRADES 
*LINK/DEBUG GRADES 
*RUN GRADES 

VAX -11 DEBUG Version 3*0--5 
%DEBUG-:i: -INITIAL? Language is FORTRAN? module set to "GRADES' 

DBG> SET LOG SESSION* DAT 

DBG> SET OUTPUT LOG 

DBG> EXAMINE DONE 

GRABESNDONE < 1 * 4 ) J 

DBG> DEPOSIT DONE* 'YES' 

DBO> EXAMINE DONE 

GRADES\DONE (1!4)! YES 

DBG> SET WATCH DONE 

DBG> SHOW WATCH 

watchpoint 3t GRADES\D0NE(.U4) for 4* bates* 

DBG> GO 

routine start 3t GRADES 

Student name? JOE SMITH 

Input sirade (or to end input)* 6 

Input sirade (or to end input) J 7 

Input j-Srade (or to end input)? 

Student J JOE SMITH Average*- 6*5 

Are «ou done ? (Yes/No) N 

write to GRADES\DONE( 1 .4) at PC 63269 

old value = YES 
new value -= N 



(using TRACE while watching DONE) 



DBG> SET TRACE KLINE 8 

DBG> SET TRACE %LINE 13 

DBG> SET TRACE %LINE 19 

DBG> GO 

start at 63279 

trace at GRADES\%LABEL 10 

Student name? MARY HAGERTY 

trace at GRADES\%LINE 13 

Input sfrade (or to end input)* 9 

Input sirade (or to end input)* 9 

Input grad® (or to end input)* 

Student* MARY HAGERTY Average* 9*0 
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brace 3t GRADES\%LINE 19 

Are hou done ? (Yes/No) N 

write to 6RADES\D0NE< 1 M) at PC 63269 

old value * N 

new value ~ N 



(Stop watching DONE. Set break point) 



DBG> CANCEL WATCH DONE 

DBG> SET BREAK ZLINE 23 

DBG> GO 

start at 63279 

break at GRADES\%LINE 23 

DBG> GO 

start at GRADES\%LINE 23 

trace at GRADESXZLABEL 10 

Student name? GERALD HORNER 

trace at GRADES\%LINE 13 

Input s$rade (or to end input)? SO 

Input sir&die (or to end input) J 100 

Input ssrade (or to end input)* 

Student: GERALD HORNER Average! 75*0 

trace at GRADES\%LINE 19 

Are hou done ? (Yes/No) N 
break at GRADES\%LINE 23 



(Try to watch TOTAL. Doesn't work.) 



DBG> SET WATCH TOTAL 

ZDEBUG-W-NOSYMBOL* symbol 'TOTAL' is not in the symbol table 



(The symbol TOTAL is in subroutine.) 



DBG> SHOW MODULE 

module name symbols size 

GRADES yes oy> 

COMPUTE no 304 

total FORTRAN modules} 2* remaining size J 56776* 



(The symbol table of subroutine must be loaded) 

DBG> SET MODULE COMPUTE 
DBG> SHOW MODULE 

rnfnco n8M symbols size 

GRADES 

COMPUTE 

total FORTRAN modules? 2. 



yes 272 
yes 304 

remaining size? 56572, 



(Now we can watch TOTAL. ) 
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DBG> SET WATCH TOTAL 

DBG> GO 

start at GRABES\%LINE 23 

trace at GRADES\%LABEL 10 

Student name? JENNY GRATIN 
trace at GRABES\%LINE 13 

write to COMPUTEXTOTAL at PC COMPUTE\%LINE 7 

old value = 155*0000 

new value - 0*0000000E+00 
BBG> GO 

start at COMPUTE\%LABEL 10 
Input sfrade (or to end input)} 5 

write to COMPUTEXTOTAL at PC COMPUTE\%LINE 16 
old value ™ 0*0000000E+00 
new value = 5*000000 

BBG> GO 

start at COMPUTE\%LINE 17 

Input sfrade (or to end input) J 6 

write to COMPUTEXTOTAL at PC COMPUTE\%LINE 16 
old value ~ 5*000000 
new value = 11*00000 

BBG> GO 

start at COMPUTENZLINE 17 

Input sfrade (or to end input)? 

Student? JENNY GRATIN Average? 5*5 

trace at GRADES\%LINE 19 

Are you done ? (Yes/No) N 
break at GRADES\%LINE 23 
DBG> SHOW SCOPE 
scope? i: = GRADES 1 
DBG> SET SCOPE COMPUTE 

DBG> SHOW SCOPE 

scope* COMPUTE 

BBG> SHOW TRACE 

tracepoint at GRABES\%LINE 19 

tracepoint at GRADES\%LINE 13 

tracepoint at GRADES\%LINE 10 

DBG> CANCEL WATCH TOTAL 
(Cancel traces at lines 13 and 19, module GRADES)- 
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DBG> CANCEL TRACE ZLINE 13 
DBO> CANCEL TRACE %LINE 19 
DBQ> SHOW TRACE 
tracepoint at GRABES\%LABEL 10 



(Try to cancel trace at line 10, module GRADES) 



DBG> CANCEL TRACE %LABEL 10 
XDEBUG-I-NOSUCHTPT* no such tracepoint 
DBG> SHOW TRACE 
tracepoint at GRADES\%LABEL 10 

(Doesn't work because scope is not set to GRADES) 

DBG> SET SCOPE GRADES 

DBG> CANCEL TRACE %LABEL 10 

DBG> SHOW TRACE 

%DEBUG-I-NOTRACESy no tracepoints are set» no opcode tracing 



(Add a tracepoint in main routine and subroutine ) 



DBG> SHOW SCOPE 
scope* GRADES 

DBG> SET TRACE %LINE 10 

DBG> SET TRACE XLINE C0MPUTEX9 

DBG> SHOW TRACE 

tracepoint at CGMPUTE\%LABEL 10 

tracepoint at GRADES\%LINE 10 



(If duplicate labels, can specify in normal 

way if scope is set to module containing 
label to be specified. If scope is not set, 
must specify module name also. 

DBG> GO 

start at GRADES\%LINE 23 

trace at CGMPUTE\%LABEL 10 

Input sirade (or to end input)? 6 

trace at COMPUTE\%LABEL 10 

Input &r&de (or to end input)? 

Student? CRAIG SMYTHE Average? 6.0 

Are you done ? (Yes/No) N 
break at GRADES\%LINE 23 



(Cancel all tracepoints) 



DBG> CANCEL TRACE/ALL 
DBG> SHOW TRACE 

%DEBUG-I-NOTRACESy no tracepoints are set? no opcode tracing 

DBG> GO 

start at GRADES\%L1NE 23 
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Student name? HORACE 0' TOOLE 

Input arade (or to end input) J 8 
Input sirade (or to end input)? 

Student: HORACE 0' TOOLE Average! 

Are wou done ? (Yes/No) N 
break at GRADES\%LINE 23 

• (Evaluate the expression TOTAL/ICOUNT) 



8.0 



DBG> 

DB0> 

DBQ> 

routi 

break 

DBG> 

DBG> 

start 

write 



SET SCOPE COMPUTE 
SET BREAK %LINE 20 

GO 

ne start at GRADES\%LINE 23 

at COMPUTERLIKE 20 
SET WATCH COMPUTENAVERAGE 
GO 



DBG> 

9. 
DBG> 
$ 



at CGMPUTE\%LINE 20 

to GRADESXAMERAGE at PC COMPUTE\%LINE 20 +7 
old value = O.OOOOOOOEfOO 
new value ~= 9.000000 
EVALUATE TOTAL/ICOUNT 
000000 
EXIT 
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EXAMPLE 4 — Aborting and restarting the debugger 



*FQRTRAN/DEBUG/LIST GRADES 
$L INK/DEBUG GRADES 
*RUN GRADES 



VAX- 11 DEBUG Version 3*0-5 

%DEBUG~I-INITIALf Language is FORTRAN!- module set to "GRADES" 

DBG>GQ 

routine start at GRADES 

Student name? SUZY QUE 

Input grade (or to end input) J 4 

Input grade (or to end input)* 9 

Input grade (or to end input); 

~Y 

$ CONTINUE 

Student? SUZY QUE Average; 6*5 

Are you done ? (Yes/No) N 

Student name ? SUZY QUE 

Input arade (or to end input); 4 

Input grade (or to end input); 9 

Input grade (or to end input); 

~Y 

♦DEBUG 
DBG>G0 
start at 2147410216 

Student; SUZY QUE Average; 6*5 

Are you done ? (Yes/No) N 
break at GRADES\%LINE 23 
DBG>EXIT 
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with VAX-11 MACRO 

5.5 PROGRAM DEVELOPMENT WITH MACRO 

VAX-11 MACRO is the assembly language for VAX/VMS. This 
language is provided with the VMS software. Examples of 
programs written in VAX-11 MACRO can be found in the 
majority of the manuals for VMS. The language reference 
manual and user's guide for VAX-11 MACRO are provided as 
part of the documentation set. 

5.5.1 SOURCE FILES 

A MACRO statement consists of the following fields: 

o A label field. A label is a symbol used to refer 
to a location in your program. A label can be up 
to 31 characters long and can contain underscore 
(_) and dollar sign ($) characters. Terminate the 
label field with a colon (:), a double colon (::) 
or a space. If a label extends past column 7, 
place it on a line by itself; place the operator 
on the following line beginning at column 9. 
Labels are optional. 

o An operator field. An operator specifies the 
action to be performed by a statement. The 
operator can be a symbol for an instruction, an 
assembler directive or a macro instruction. 
Terminate the operator field with a tab. The 
operator field is required. 

o An operand field. The operand field contains 
symbolic names or specifications for the addresses 
of one or more operands. Operands specify 
instruction operands, assembler directive 
arguments, or macro arguments. The operand field 
is required. 

o A comment field. A comment contains text that 
explains the function of the preceding statement. 
Ideally, you should comment every line of MACRO 
code, but they are optional elements of any MACRO 
statement. A comment can be continued from one 
line to the next. A comment can appear on a line 
by itself. Mark the beginning of any comment with 
a semicolon ( ;) . 

The format of a complete MACRO statement is: 

Label: Operator Operandi, Operand 2, .. . ;Comment 
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A statement can be continued on several lines by using 
a hyphen (-) as the last non-blank character before the 
comment field. 

Conventionally, each field should begin at the column 
indicated by Table 5-4 for readability. The TAB key 
should be used the number of times indicated in the 
table to move the cursor to the correct column to begin 
input. 

Table 5-4 Formatting Conventions for MACRO Statements 
Field Column Tab Characters 



Label 1 

Operator 9 1 

Operand 17 2 

Comment 41 5 
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5.5.2 PREPARING THE PROGRAM FOR EXECUTION 

Source programs written in VAX-11 MACRO must be 
assembled, not compiled. The assembler produces an 
object file which must be linked to produce an 
executable image. The following is an example of the 
steps of program development for a program written in 
MACRO: 

1. $EDIT GRADES. MAR 
Creates the source file. 

2. $MACRO/LIST/ENABLE=DEBUG GRADES 

Assembles the source code, producing an object file 
and a listing file. 

3. $LINK/DEBUG GRADES 

4. $RUN GRADES 

5. DBG> GO 

Control passes to the symbolic debugger 
automatically on execution of the program. To run 
the program, the debug command GO should be 
entered . 
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5.5.3 DEBUG COMMANDS 

Refer to the list of debug commands in the discussion 

of the FORTRAN language, Section 5.6.3. Debug commands 

for MACRO programs can be entered using the same format 
except for : 

1. The MACRO programmer usually has a better idea of 
what is occurring in their program than the 
high-level language programmer. Therefore, 
commands such as DEPOSIT and EXAMINE are used to a 
greater extent. Locations such as the program 
counter, offsets from the argument pointer, and 
places in memory can be examined and the 
information returned is usually helpful. Locations 
are specified using the same syntax as in a MACRO 
program (PC, @AP, @AP+5, R2 f @AP:@AP+0C, 400). 

2. The DEFINE command is useful for making it easier 
to work in the debugger. Symbolic names can be 
assigned to addresses. After the DEFINE command is 
used, the symbolic name can be specified instead of 
the address. For example, 

DBG> EXAMINE GRADES+4 

contents of the location GRADES+4 

DBG> DEFINE PLACE = GRADES+4 

DBG> EXAMINE PLACE 

contents of the location GRADES+4 



3. The DEPOSIT command can be used to change an 
instruction if the SET TYPE INSTRUCTION command is 
input first. For example; 

DBG> SET TYPE INSTRUCTION 

DBG> EXAMINE PLACE 
PLACE: MOVL @B~A_SORTED(AP) [R2] ,§B"A_SORTED (AP) [R2] 

DBG> DEPOSIT PLACE=' MOVL @B~A ARRAY (AP) [R2] ,- 

@B"A_SORTED(AP) [R2] ' 

DBG> EXAMINE PLACE 
PLACE: MOVL @B~A ARRAY (AP) [R2] ,@B~A SORTED (AP) [R2] 



4. The SET TYPE command can be used to change the 
default type to other types so the EXAMINE and 
DEPOSIT commands can be used as intended. 
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5.6 PROGRAM DEVELOPMENT WITH FORTRAN 



5.6.1 SOURCE FILES 



A line in a FORTRAN source program consists of five 
fields : 

o Comment Indicator Field 

o Statement Label Field 

o Continuation Indicator Field 

o Statement Field 

o Sequence Number Field 



There are two ways to format these fields in a FORTRAN 

line : 

1. By means of "character-per-column" formatting 

2. By means of "tab" formatting 

5.6.1.1 CHARACTER-PER-COLUMN FORMATTING 

Character-per-column formatting is used on VAX-11 
systems to preserve compatibility with existing 
FORTRAN programs and those intended to be 
transportable between systems. The 
character-per-column format is the format used on 
punched cards, and is specified in the ANSI 
standard for the FORTRAN language. 

The character-per-column format requires that each 
field of a FORTRAN line begin in a particular 
column. The columns that correspond to each field 
in a VAX-11 FORTRAN line are listed in Table 5-5. 
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Table 5-5 Column Conventions for FORTRAN 
Column ANSI Standard Definition 



1 
2-5 

6 
7-72 
73-80 



Comment indicator (C) 
Line number 

Continuation indicator 
Valid FORTRAN statement 
Sequence number 



5.6.1.2 TAB FORMATTING 



VAX-11 FORTRAN allows the use of the TAB key to 
input lines of code. The compiler translates the 
TAB character differently depending on where it is 
entered in the line. Use of the TAB key makes it 
easier to create FORTRAN source files. 

Table 5-6 shows the action taken by the compiler 

when it encounters the TAB character, or any 

characters that are not in the fields defined for 
them by the ANSI standard. 
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Table 5-6 Using Tab Formatting 
If you type: then the compiler assumes 



<TAB>text 



<TAB>#text 



#<TAB>text 



C text 



D text 



text J comment 



text in columns 
73-80 



The text is a valid FORTRAN 
statement and places it in columns 
7-72 

The number (#) is a continuation 
mark, and places it in column 6, 
followed by the text which starts 
in column 7 

The number (#) is a line number (or 
statement label), and places it in 
columns 2-5, followed by the text 
which starts in column 7 

The entire line is a comment and 
ignores it 

The entire line is a comment and 
ignores it unless the /D_LINES 
qualifier is included with the 
compiler command. If the /D_LINES 
qualifier is included, the compiler 
assumes the line contains a valid 
FORTRAN statement, and processes it 

The text is a valid FORTRAN statement, 
and anything following an exclamation 
point is a comment; to be ignored 

The text is a comment and ignores it 
unless the /EXTEND qualifier is 
included with the compiler command. 
If the /EXTEND qualifier is included, 
the compiler assumes the text is a 
continuation of the current line, or a 
valid FORTRAN statement, and processes 
it 
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5.6.2 PREPARING THE PROGRAM FOR EXECUTION 

Assuming the source file has been created, the next 
step is compilation followed by linking; then the 
program can be executed. This list, an example of the 
steps in program development for a FORTRAN program, is 
followed by a partial listing of the program developed. 
The debugging session in section 5.4.1 uses the line 
numbers in the far-left column of the listing file, as 
well as the variable and subroutine names shown. 

1. $EDIT GRADES. FOR 
Creates the source file. 

2. $FORTRAN/LIST/NOOPTIMIZE/DEBUG GRADES 

Code is normally optimized by the FORTRAN compiler. 
Optimization involves methods which can decrease 
the effectiveness of the symbolic debugger. When 
using the debugger, the /NOOPTIMIZE qualifier 
should always be included to ensure close 
correspondence between the object code produced by 
the compiler and the source code. 

3. $LINK/DEBUG GRADES 

4. $RUN GRADES 

5. DBG>GO 

Control passes to the symbolic debugger immediately 
on execution of the program. To run the program, 
the debug command GO should be entered. 
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Listing of Main Proara* 



0001 




0002 




0003 




0004 




0005 




0006 




0007 




0008 


10 


0009 


20 


0010 




0011 


30 


0012 




0013 




0014 




0015 




0016 




0017 


40 


0018 




0019 




0020 


50 


0021 




0022 


60 


0023 




0024 




0025 




0026 





PROGRAM GRADES 

CHARACTER STUDENT_NAME*30r D0NE*4 
REAL AVERAGE 

OPEN (UNIT=1f FILE-'Course't STATUS='New' ) 

TYPE 20 

FORMAT (/' Student name? '»$) 
ACCEPT 30. STUDENT.NAME 
FORMAT <1A30) 

CALL Get.arades-compute-averasie (AVERAGE) 

TYPE 40»STUDENT_NAME» AVERAGE 

URITE (1,40) STUDENT_NAMErAVERAGE 

FORMAT (/' Student! ' >A30i 'Average: '.F10.1) 

TYPE 50 

FORMAT (/' Are you done ? <Yes/No) '»*> 

ACCEPT 60» DONE 

FORMAT (1A4) 

IF (DONE.NE.'Y' .AND. DONE.NE.'y') GOTO 10 

CLOSE <UNIT=1) 
END 



Listing of Subroutine 



0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
0020 
0021 
0022 
0023 



SUBROUTINE Get_2rades_coi»pute_aver3Se (AVERAGE) 

INTEGER ICOUNT 
REAL TOTALi GRADE 

ICOUNT = 

TOTAL ■ 

10 TYPE 20 

20 FORMAT (' Input Srade (or to end input)} 'i*> 

ACCEPT 30 f GRADE 
30 FORMAT (F10.0) 

IF (GRADE. NE.O) THEN 

ICOUNT = ICOUNT + 1 

TOTAL = TOTAL + GRADE 

GO TO 10 
ENDIF 

40 IF (ICOUNT, NE.O) AVERAGE = TOTAL/ICOUNT 

RETURN 
END 
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5.6.3 DEBUG COMMANDS 

One example of each of the debug commands used in the 
sample debug session in section 5.4.1 follows: 

SET LOG FILE. DAT 

SET OUTPUT LOG 

SET BREAK %LINE 23 

SET MODULE COMPUTE 

SET SCOPE COMPUTE 

SET TRACE %LINE 8 

(Trace and break statements can not be set at 
blank lines, comment lines, or lines where a 
FORMAT statement is specified.) 

SET WATCH DONE 

SHOW BREAK 

SHOW MODULE 

SHOW SCOPE 

SHOW TRACE 

SHOW WATCH 

EXAMINE DONE 

DEPOSIT DONE='YES' 

EVALUATE TOTAL/ICOUNT 

CANCEL BREAK %LINE 23 

CANCEL TRACE %LINE 8 

CANCEL TRACE/ALL 

CANCEL WATCH DONE 

CANCEL ALL (equivalent to CANCEL BREAK/ALL) 

GO 

EXIT 
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5.7 PROGRAM DEVELOPMENT WITH PASCAL 

5.7.1 SOURCE FILES 

All procedures and functions should be in the 
declaration section of a PASCAL program. Any of these 
may be removed and placed in a separate source file. 
The source file containing the main program must begin 
with the statement PROGRAM. The source files 
containing procedures and functions must begin with the 
statement MODULE. 

5.7.2 PREPARING THE PROGRAM FOR EXECUTION 

Assuming the source file has been created, the next 
step is compilation followed by linking; then the 
program can be executed. This list, an example of the 
steps in program development for a PASCAL program, is 
followed by a partial listing of the program developed. 
The line numbers shown in the left-hand column are used 
for symbolic debugger commands requiring line numbers. 

1. $EDIT GRADES. PAS 
Creates the source file. 

2. $PASCAL/LIST/DEBUG/NOSTANDARD/NOWARNING GRADES 

Non-standard features, including underscores (_) in 
identifier names, the OPEN statement, and carriage 
control specifications in the WRITELN statement, 
can be used in a VAX-11 PASCAL program. The VAX-11 
PASCAL compiler displays a warning message each 
time it encounters one of these extensions. To 
suppress the messages, use the /NOSTANDARD 
qualifier with the compiler command. To suppress 
warning messages regarding unorthodox, but 
acceptable syntax in a program, the /NOWARNING 
qualifier is used. 

3. $LINK/DEBUG GRADES 

4. $RUN GRADES 

5. DBG>GO 

Control passes to the symbolic debugger immediately 
on execution of the program. To run the program, 
the debug command GO should be entered. 
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Pascal Source Listing 

PROGRAM Grades (Course. INPUT. OUTPUT)? 



0001 

0002 

0003 

0004 

0005 

0006 

0007 

0008 

0009 

0010 

0011 

0012 

0013 

0014 

0015 

0016 

0017 

0018 

0019 

0020 

0021 

0022 

0023 

0024 

0025 

0026 

0027 

0028 

0029 

0030 

0031 

0032 

0033 

0034 

0035 

0036 

0037 

0038 

0039 

0040 

0041 

0042 

0043 

0044 

0045 

0046 

0047 

0048 

0049 

0050 



TYPE 

Yes-no = (aes.no)? 
VAR 

Student-name J PACKED ARRAY CI.. 403 OF CHAR? 

Course 2 TEXT. 

Icount : INTEGER? 

Done * Yes-no? 

Grade. Total. Average 2 REAL? 

St. Av 2 PACKED ARRAY CI.. 10] OF CHAR? 



VALUE 

St t= 'Student: '? 



Av 2 = 'Average! 



PROCEDURE Compute. 
BEGIN 

Icount 2 = 0? Total 2 = 0? 
REPEAT 
WRITE (' Input grade (or to end input)? ')? 
READ (Grade)? 
IF Grade <> 

THEN Icount 2 = Icount + 1? 

Total 2 = Total + Grade? 
UNTIL Grade = 0? 
Average 2 = Total / Icount? 
END? 

BEGIN < Main Procedure > 

REWRITE (Course)? 
REPEAT 

< Get information for one student > 

WRITELN? 

WRITE ('Student name? ')? 

READ (Student-Name). 

Compute? 

< Output results to terminal and file > 

WRITELN? WRITELN? 

WRITELN (St. Student-Name. Av. Average 2321)? 

WRITELN (Course. St. Student-Name. Av. Average 2321)5 

< Check if more students > 

WRITELN? 

WRITELN ('Are sou done ? (Yes/No) ')? 
READ (Done)? 
UNTIL Done - Yes? 
CLOSE (Course)? 

END < Program Grades >. 
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5.7.3 DEBUG COMMANDS 

Refer to the list of commands in the discussion of the 
FORTRAN language, Section 5.6.3. Debug commands for 
PASCAL programs are entered using identical formats 
except for : 

1. If the SET WATCH command is used to watch a 
variable that is stored on the same page in memory 
as a file variable, when the file variable is 
accessed by the program, errors occur. 

2. Trace and break statements can not be set at blank 
lines or comment lines. 

3. The COMPUTE procedure is considered as part of the 
main program, GRADES, so all variables are known to 
the debugger. Unless routines are coded in 
separate source files, and the MODULE statement is 
used, the SET SCOPE and SET MODULE commands are not 
useful in PASCAL. 

4. The DEPOSIT command for depositing 'yes' into DONE 
works differently for this version of the PASCAL 
program, because DONE is declared as a type. The 
possible values of DONE are YES and NO. Since 
these are considered to be values, not strings, the 
apostrophes are not required 

( DBG> DEPOSIT DONE=YES ) . If DONE is supposed to 
contain a string, the DEPOSIT command would be 
identical . 

5. Notice that the output from the debugger differs 
from the output when a FORTRAN module is being run. 

6. The SET WATCH command can not be used with 
variables declared in subprograms. 



PROGRAM DEVELOPMENT Page 5-45 

with VAX-11 BASIC 

5.8 PROGRAM DEVELOPMENT WITH BASIC 

5.8.1 SOURCE FILES 

VAX-11 BASIC can be used as though it were either an 
interpreter or a compiler. A fast RUN command and 
support for direct execution of unnumbered statements 
(immediate mode) gives the VAX-11 BASIC user the 'feel' 
of an interpreter. However, source programs created 
with an interactive editor can be compiled, linked, and 
run in the same manner as source programs written in 
other native-mode languages (see Section 5.1). 

Table 5-7 shows the steps of program development using 
VAX-11 BASIC in immediate mode. More information about 
immediate mode or other features of VAX-11 BASIC can be 
found in the VAX-11 BASIC documentation. Some 
information is available while the user is in immediate 
mode, if HELP is entered at the "Ready?" prompt. 

Table 5-7 BASIC Program Development Using Immediate Mode 
Steps Comments 

1. $BASIC Enters the BASIC environment. 

2. Enter program Includes line numbers 

3. [ LOAD file_spec ] (optional) Includes any programs 

needed by the main program 

4. [ COMPILE ] (optional) Compiles the program 

and any subprograms. Only used 
if you want to create an object 
file that can later that can be 
linked with other programs. 

5. run Executes program. If a CTRL/C 

is typed or a STOP statement is 
encountered, immediate mode 
debugging statements (see VAX-11 
BASIC User's Guide) may be 
entered . 
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5.8.2 PREPARING THE PROGRAM FOR EXECUTION 

Assuming the source file has been created, the next 
step is compilation followed by linking; then the 
program can be executed. This list, an example of the 
steps in program development for a BASIC program, is 
followed by a partial listing of the program developed. 

1. $EDIT GRADES. BAS 

2. $BASIC/LIST/DEBUG GRADES 

3. $LINK/DEBUG GRADES 

4. $RUN GRADES 

5. DBG>GO 

Control passes to the symbolic debugger immediately 
on execution of the program. To run the program, 
the debug command GO should be entered. 
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Listing of Main Program 



1 10 

1 

1 15 

1 

1 20 

2 

1 

1 30 

1 

1 40 

2 

2 

2 

2 

3 



60 

990 
999 



! PROGRAM GRADES 
! 

OPEN 'Course' FOR OUTPUT AS FILE IX 
! 

PRINT 

INPUT 'Student name' J STUDENT-NAME* 

i 

CALL COMPUTE (AVERAGE) 



PRINT 
PRINT 



PRINT #1% 
PRINT *lXt 



'Student: "t 
STUDENT-NAME*. 

AVERAGE 

'Student: '» 
STUDENT-NAME*. 

AVERAGE 



Average: '% % 



Average* 



PRINT 

INPUT 'Are you done (Yes/No) '» DONE* 

IF DONE* <> '*' AND DONE* <> 'Y' THEN GOTO 20 

CLOSE IX 

END 






Listing of Subprogram 



1 10000 

1 1 

1 10010 

2 

1 ! 

1 10020 

1 ! 

1 10030 

2 

3 

4 

1 ! 

1 10040 

2 

1 ! 

1 10099 



SUB COMPUTE (AVERAGE) 

ICOUNT - OX 
TOTAL = 0% 

INPUT 'Input grade (or to end input) 'J GRADE 



IF 
THEN 



IF 
THEN 

SUBEND 



GRADE <> OX 
ICOUNT = ICOUNT + 1% 
TOTAL = TOTAL + GRADE 
GOTO 10020 

ICOUNT <> 0% 

AVERAGE = TOTAL/ICOUNT 



PROGRAM DEVELOPMENT Page 5-48 

with VAX-11 BASIC 



5.8.3 DEBUG COMMANDS 

Several kinds of variables are initialized at run-time 
before the code in a VAX-11 BASIC program is executed. 
Therefore, before examining the contents of any 
variables, set a breakpoint at the first statement, and 
input the GO command. This is true for subprograms as 
well. The initialization is done as you enter the 
subprogram. Therefore, before examining variables in a 
subprogram, set a breakpoint at the first statement in 
the subprogram and GO to that point. 

Most implementations of the BASIC language require the 
user to input line numbers for each line of source 
code. Users of VAX-11 BASIC are not required to input 
any line numbers. However, each line must be numbered 
in the listing so the user can use the debugger and 
specify a particular line. The VAX-11 BASIC compiler 
does not generate more line numbers in the listing 
file. Instead, the line numbers in the source code are 
used in debug commands in a special way. 

In VAX-11 BASIC, several source statements can share 
the same line number. The first source statement 
associated with a line number is assigned the number 1, 
which appears in the left-hand column of the listing 
file. The second source statement is assigned the 
number 2, and so on. In some cases, a particular 
source statement is continued over several text lines. 
In the listing, each line will be assigned the same 
number. 

To designate a particular source line to the debugger, 
specify the line number associated with that line. If 
the statement is the second statement associated with 
the line number, specify the line number, a period, and 
the number 2 (line_number . 2) . 

For example, look at the statement with the line number 
40 in the listing of the GRADES program. Four source 
statements are associated with line 40. To set a 
breakpoint at each, the following commands should be 
used: 

DBOSET BREAK %LINE 40.1 

DBOSET BREAK %LINE 40.2 

DBOSET BREAK %LINE 40.3 

DBOSET BREAK %LINE 40.4 



The first line number can be specified using 40.1 or 40 

(the 1 is implied) . Line numbers can be specified in 

the same manner for other debug commands requiring 
them. 
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5.9 PROGRAM DEVELOPMENT WITH COBOL 



5.9.1 SOURCE FILES 

The VAX-11 COBOL compiler accepts two source program 
coding formats: ASNI standard and terminal. Both 
formats are described in terms of character positions 
in a line. The ANSI standard, (sometimes call 
conventional), format is based on the traditional COBOL 
format as applied to an 80-column punched card. The 
terminal format is a DEC-specif ied format for 
convenient use with an interactive text editor. 

Table 5-8 compares the two formats. Notice that the 
terminal format does not allow the sequence number or 
identification fields, and both formats accept tab 
characters or carriage return characters as line 
terminators. 



Table 5-8 Character Positions in COBOL Source Files 

COLUMNS 
Fields ANSI Standard Terminal 



Sequence numbers 


1-6 


Continuation/Comment 
Indicator Area 


7 


Area A 


8-11 


Area B 


12-72 


Identification Field 


73-80 



not used 

1 

1-4 
5-56 
not used 



Tab stops are defined by the compiler depending on the 
format used. 

For ANSI standard format, they are set at: 

7, 8, 12, 20, 28, 36, 44, 52, 60, 68, 73 

For terminal format they are set at: 
5, 13, 21, 29, 37, 45, 53, 61, 66 
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Terminal format is the compiler default. The use of 
terminal format saves a considerable amount of space in 
a source file on disk as compared to the use of ANSI 
standard format. For this reason, if you have files on 
a disk which are in ANSI standard format, you may wish 
to convert them to terminal format using the REFORMAT 
utility. This utility can also be used to convert a 
file in terminal format to conventional format. The 
DCL command to invoke the REFORMAT utility is: 

$RUN SYS $SYSTEM: REFORMAT 



The utility will then prompt you for all pertinent 
information. The REFORMAT utility is described in the 
VAX-11 COBOL User's Guide. 



5.9.2 PREPARING THE PROGRAM FOR EXECUTION 

Assuming the source file has been created, 



the next 
then the 
a COBOL 



step is compilation followed by linking; 

program can be executed. When you compile 

program, the compiler will assume that you are using 

terminal format unless you specify the /ANSI_FORMAT 

qualifier. ~ 

This list, an example of the steps in program 
development for a COBOL program, is followed by a 
partial listing of the program developed. The line 
numbers shown in the left-hand column can be used with 
symbolic debugger commands requiring line numbers. 

1. $EDIT GRADES. COB 

2. $COBOL/LIST/DEBUG GRADES 



or 
$COBOL/ANSI_FORMAT/LIST/DEBUG GRADES 

3. $LINK/DEBUG GRADES 

4. $RUN GRADES 

5. DBG>GO 

Control passes to the symbolic debugger immediately 
on execution of the program. To run the program, 
the debug command GO should be entered. 
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Source Listing 

1 * PROGRAM GRADES 

2 # 

3 IDENTIFICATION DIVISION. 

4 * 

5 PROGRAM-ID. GRADES. 

6 * 

7 ENVIRONMENT DIVISION. 

8 INPUT-OUTPUT SECTION. 

9 FILE-CONTROL. 

10 SELECT COURSE ASSIGN TO 'COURSE'. 

11 DATA DIVISION. 

12 FILE SECTION. 

13 FD COURSE 

14 LABEL RECORDS ARE STANDARD. 

15 01 OUT-REC PIC X<72). 
16 

17 WORKING-STORAGE SECTION. 

18 01 STUDENT-NAME PIC X<40>. 

19 01 AVERAGE PIC 999V999 COMP. 

20 01 DONE PIC X<4). 

21 01 OUT-LINE. 

22 05 FILLER PIC X<9> VALUE IS "Student: '. 

23 05 OUT-NAME PIC X(40). 

24 05 FILLER PIC X<16> VALUE IS " AveraaeJ *. 

25 05 OUT-AVG PIC ZZ9.999. 
26 

27 PROCEDURE DIVISION. 

28 BEGIN. 

29 OPEN OUTPUT COURSE. 
30 

31 ACCEPT-STUDENT. 

32 DISPLAY ". 

33 DISPLAY ". 

34 DISPLAY 'Student nane? ' WITH NO ADVANCING. 

35 ACCEPT STUDENT-NAME. 

36 CALL 'Get-Srades-coapute-averase" USING BY REFERENCE AVERAGE. 

37 MOVE STUDENT-NAME TO OUT-NAME. 

38 MOVE AVERAGE TO OUT-AVG. 

39 DISPLAY ■'. 

40 DISPLAY ". 

41 DISPLAY OUT-LINE. 

42 WRITE OUT-REC FROM OUT-LINE. 
43 

44 DISPLAY 

45 DISPLAY 'Are you done <Y/N>? ' WITH NO ADVANCING. 

46 ACCEPT DONE. 

47 IF DONE IS NOT EQUAL TO "Y" AND DONE IS NOT EQUAL TO '«' 

48 THEN GO TO ACCEPT-STUDENT. 
49 

50 CLOSE COURSE. 

51 STOP RUN. 

52 END PROGRAM GRADES. 



PROGRAM DEVELOPMENT Page 5-52 

With VAX-11 COBOL 



Source Listing of Subprogram 

53 
54 
55 
56 

57 IDENTIFICATION DIVISION. 

58 * 

59 PROGRAM-ID. 6et_Srades_coiriPute_aver8de. 

60 * 

61 * 

62 DATA DIVISION. 

63 WORKING-STORAGE SECTION. 

64 01 IN-GRADE PIC 999. 

65 01 GRADE PIC 999 COMP. 

66 01 ICOUNT PIC 999 COMP. 

67 01 TOTAL PIC 999 COMP. 
68 

69 LINKAGE SECTION. 

70 01 AVERAGE PIC 999V999 COMP. 
71 

72 PROCEDURE DIVISION USING AVERAGE. 

73 BEGIN. 

74 MOVE ZERO TO ICOUNT. 

75 MOVE ZERO TO TOTAL. 
76 

77 DISPLAY 

78 DISPLAY "". 

79 DISPLAY '(Grades must be 3-diaits Ions. Pad with leading O's.)' 

80 DISPLAY '". 

81 ACCEPT-GRADE. 

82 DISPLAY "Enter grade (or 000 to end input)} ■ 

83 WITH NO ADVANCING. 
84 

85 ACCEPT IN-GRADE. 

86 

87 IF IN-GRADE IS NOT EQUAL TO THEN 

88 ADD 1 TO ICOUNT 

89 ADD IN_GRADE TO TOTAL 

90 GO TO ACCEPT-GRADE 

91 END-IF. 
92 

93 IF ICOUNT IS NOT EQUAL TO THEN 

94 DIVIDE ICOUNT INTO TOTAL GIVING AVERAGE. 
95 

96 EXIT PROGRAM. 

97 

98 END PROGRAM Get-sfrades.conpute-8vera3e. 
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5.9.3 DEBUG COMMANDS 

Debug commands for programs written in COBOL are 
identical to those for FORTRAN programs (see Section 
5.6.3) with the exception of: 

1. SET WATCH is not available when files are used. 

2. STEP is used to step 1 instruction at a time. The 
specification of a certain number of steps is not 
available. 

3. The TYPE command can be used to type out source 
statements in modules. Line numbers specified are 
those output in the listing file. TYPE is unique 
to COBOL. An example follows: 



DBG? 


• TYI 


"•E IS 4 








module 1 


3RADES 










:l. * 


* PROGRAM 


GRADES 






2 J 


* 










3* 


IDENTIFICATION 


DIVI 


SION* 




4J 


* 








DBG? 


► TYPE 55 








module i 


BRACES 










crer ♦ 











DBG> TYPE 65169 

module GRADES 

XDEBUG-W-NOLINXXX* lines 

DBG> SHOW MODULE 

module name 

GRADES 

COMPUTE 

COB*RMS-BLOCKS 

LIB*AB_CVTTP_U 

total modules* 4* 

DBG> SET MODULE COMPUTE 

DBG> TYPE 65* 

module GF 

%DEBUG-W-NOLINXXX» lines 

DBG> TYPE C0MPUTE\65 J 69 

module compute 



5*69 do not 


exi 


st in module GRADES 


symbol 


,s 


language 


s i ze 


yes 




COBOL 


560 


no 




COBOL 


364 


no 




BLISS 


C*) 


no 




MACRO 


104 


remaining s:i 


.zei 


56980* 





>d»69 



65*69 do not exist in module GRADES 



65* 


0.1. 


GRADE 


c>6> * 


01 


I COUNT 


67 * 


01 


TOTAL 


68 « 






69 J 


LINKAGE 


SECTION* 



PIC 
PIC 
PIC 



999 
999 
999 



COMP, 
COMP ♦ 
COMP . 
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DBG> SET SCOPE COMPUTE 

DBG> TYPE 65 J 69 

module commute 

65: 01 GRADE 
661 01 ICOUNT 
01 TOTAL 



671 

68 ♦ 

69: 



LINKAGE SECTION, 



DBG> EXIT 



PIC 999 COMP* 
PIC 999 CQMP. 
PIC 999 COMP* 



CHAPTER 6 
SIMPLIFYING A USER SESSION 



User sessions can be simplified through the use of command 
procedures and symbols. This is especially helpful for the 
frequent user. Command procedures are usually created to 
perform specified or repetitive jobs. 

A command procedure is a text file, created by an editor. 
It contains a list of DCL commands, and is formatted in a 
standard way. The DCL interpreter can read the DCL commands 
from the file instead of from the user's terminal. By 
placing commonly used DCL command sequences in a file, the 
user can more easily interact with the system. 

A symbol is a series of characters representing part or all 
of a DCL command. The series of characters for a symbol is 
chosen by the user. Using symbols gives the user the 
ability to tailor the DCL command language for themselves. 



6.1 CREATING A COMMAND PROCEDURE 

Command procedures are an easy way of entering commonly-used 
DCL command sequences. Since all the necessary commands are 
in a file, the exact order and form of the commands is 
recorded. Once entered into a file, a command procedure can 
be used as many times as needed. The continued reuse of a 
command procedure saves users the time needed to find the 
correct command sequence and enter it each time. 

When the user is working at a terminal, the DCL interpreter 
outputs a prompt, $, to indicate when it is ready to receive 
a command. When a command procedure is created, each 
command listed should be preceded by a $. Any line not 
preceded by a $ will be treated as data, not as a command. 
(Note: The $ should always be entered in the first column 
of the line.) 
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After you create a command procedure, you can execute all 
the commands in it with a single command. For example, 
suppose a procedure named PR0CESS.COM contains the lines: 

$FORTRAN/LIST PROGRAM. FOR 
$PRINT PROGRAM. LIS 
$LINK PROGRAM. FOR 
$RUN PROGRAM. FOR 

The commands in this file can be executed by entering the 
following command at the DCL prompt: 

$§PROCESS 

The @ (execute procedure) command assumes the filetype is 
.COM. Each command in the command procedure is executed in 
the order specified. 

The commands in a DCL command procedure are not normally 
displayed as they are executed. The user will see any 
output or error messages normally associated with the 
command, but not the command itself. If the user inputs the 
SET VERIFY command, the commands will be seen. Commands 
will continue to be seen for all command procedures 
subsequently executed until a SET NOVERIFY is input. 

The SET commands can be included in the command procedure or 
entered interactively by the user. Users will find the SET 
VERIFY command to be especially helpful when a new procedure 
has been created, and they are trying to determine whether 
it is working as intended or not. For example: 

User creates three files: 

SH0W.COM SH0W2.COM D0.COM 

$SH0W TIME $SET VERIFY $@SH0W 

$SH0W USERS $SH0W TIME $@SH0W2 

$SH0W USERS $@SH0W 
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User invokes the DO.COM procedure in an interactive session 
and observes the output: 

$@D0 

5-APR-1982 09:57:25 
VAX/VMS Interactive Users - Total = 1 
5-APR-1982 09:57:25.54 

TTA1: DRAGI 00040035 

$SH0W TIME 

5-APR-1982 09:57:25 
$SH0W USERS 

VAX/VMS Interactive Users - Total = 1 
5-APR-1982 09:57:26.07 

TTA1: DRAGI 00040035 

$@SH0W 
$SH0W TIME 

5-APR-1982 09:57:26 
$SH0W USERS 

VAX/VMS Interactive Users - Total = 1 
5-APR-1982 09:57:26.95 

TTA1: DRAGI 00040035 



Commands (if SET VERIFY is activated), output from commands, 
and error messages can be saved in a file by including the 
/OUTPUT qualifier to the @ command: 

$@D0/0UTPUT=D0. LIS 
$ 

Errors will appear on the terminal as well as in the output 
file. If no errors occur, no output will be seen. The 
output file must be printed or typed to observe the results. 

Commands should not be abbreviated in a command procedure. 
Using the complete command makes the procedure more readable 
and self-commenting. If extra comments are needed within a 
procedure, they can be placed anywhere in a line if preceded 
by an exclamation point (»). The DCL interpreter ignores 
everything on a line after an ! is read. Therefore, 
comments are not executed. 

DCL commands are normally executed in the order they appear 
in the command procedure, in the same way statements are 
executed in the order they appear in programs. 
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Some DCL commands are available to change the order of 
execution, including IP, GOTO, and EXIT. Other commands are 
available for the manipulation of files from a command 
procedure, including OPEN, READ, and WRITE. These commands 
are not needed in simple procedures, but more sophisticated 
users can learn about them through the use of the HELP 
facility. 

If any command executed in a command procedure causes an 
error or severe error to occur, an appropriate message will 
be output and the command procedure will be terminated. 
Successful commands, and those causing warning messages to 
be output, will not terminate the procedure. 

6.1.1 THE L0GIN.COM PROCEDURE 

Most users will create at least one command procedure 
with the name L0GIN.COM. This procedure, stored in the 
user's top-level directory, is executed by the system 
each time the user logs in. The L0GIN.COM file 
typically contains commands to change the user 
environment, output information to the user, and create 
symbols (see Section 6.2). For example: 

The L0GIN.COM file contains the following lines: 

$SET VERIFY 

$! 

$! Obtain information 

$! 

$SH0W SYSTEM 

$SH0W USERS 

$SH0W PROCESS 

$SH0W TIME 

$1 

$! Modify the environment 

$! 

$SET TERMINAL/VT52 

$! 

$! Create symbols 

$! 

After the L0GIN.COM has been created or modified, the 
user should always test it before logging out: 

$@L0GIN 

This precaution is necessary, because if the procedure 
contains certain errors, the user may not be able to 
log back in again. When the procedure executes without 
error, the user can log out and log in to observe that 
the system executes the procedure automatically. 
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6.2 CREATING SYMBOLS 

Symbols can be used to create synonyms for DCL commands or 
parts of DCL commands. Symbols are created through the use 
of an assignment statement. For example, the symbol LIST 
could be defined to equate to the DCL command DIRECTORY as 
follows: 

$LIST == "DIRECTORY" 

The symbol can be used as follows: 
$LIST 
(output for the directory command is seen) 

When the user inputs LIST as a command, the DCL interpreter 
looks in the table where symbols are stored and translates 
LIST to be DIRECTORY. Then the interpreter executes the 
DIRECTORY command. 

A symbol can also be equated to a portion of a command, as 
follows: 

$FL == "FORTRAN/LIST" 

Since FORTRAN/LIST requires a file specification to be 
complete, FL also requires a file specification: 

$FL PRGM.FOR 

A symbol created by a user is valid only for that user. Two 
kinds of symbols can be created, local and global. Global 
symbols are most useful to the average user, and that is the 
kind of symbol created in the previous examples. To list 
all global symbols created during a user session, the 
command "SHOW SYMBOL/GLOBAL/ALL" can be entered. To delete 
a symbol, the command "DELETE/SYMBOL/GLOBAL symbol_name" can 
be entered. 
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6.2.1 PARAMETER SYMBOLS 

Eight local symbols, called parameter symbols, are 
created automatically for the user whenever a command 
procedure is invoked. These can be used to input 
information to the procedure at the time of activation. 
The names of these symbols are PI, P2, P3, P4, P5, P6, 
P7, and P8. 

Procedures are executed with the command: 

$@f ile_specif i cat ion 

Information can be input optionally on this command 
line following the file specification. The information 
can be any string of characters. The first piece of 
information is automatically equated to the PI symbol. 
The second piece of information is equated to the P2 
symbol, and so on, up to eight pieces of information. 

Parameter symbols exist for the duration of the command 
procedure only. When the command procedure is done, 
the symbols are deleted by the system. If the 
procedure is invoked again, the symbols are re-created. 

Parameter symbols are commonly used to input file names 
or instructions to the procedure, as shown in the 
following examples: 

Example 6-1 

The file PR0CESS.COM contains the following statements: 

$SET VERIFY 

$FORTRAN/LIST 'PI' ! Notice that PI is enclosed 
$PRINT 'PI' Jin apostrophes to indicate 

$LINK 'PI' !to the DCL interpreter that 

$RUN 'PI' lit is a symbol 
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A user executes the procedure, passing PRGM as the 
value of Pi: 

$ 

$@ PROCESS PRGM 
$FORTRAN/LIST PRGM 
$PRINT PRGM 

Job 509 entered on queue SYS$PRINT 
$LINK PRGM 
$RUN PRGM 
HI 

During the execution of the command procedure, the DCL 
interpreter will substitute PRGM wherever PI appears. 
Default values for portions of file specifications not 
input are available within command procedures. 
Therefore, PRGM is sufficient, as the FORTRAN compiler 
will add the file_type of .FOR, the PRINT program will 
add the file_type of .LIS, the LINK program will add 
the file_type of .OBJ, and the RUN program will add the 
file_type of .EXE. 

Example 6-2 

The file L0G0UT.COM contains the following lines: 

$SET VERIFY 

$! 

$IF PI. NES." PURGE" THEN GOTO LOGOUT "String 

$1 comparison 

$PURGE [...]*.* 

$! 

$L0G0UT: "Label - indicated by colon 

$! terminator 

$ LOGOUT 

When the user inputs the command @L0G0UT, with no 
parameter, the LOGOUT command will be executed. If the 
user inputs any string as a parameter other than PURGE, 
the LOGOUT command will be executed. If the PURGE 
string is input for PI, then the PURGE command will be 
executed followed by the LOGOUT command. 

$@L0G0UT 

user is logged out 

$@L0G0UT JKLM 

user is logged out 

$@L0G0UT PURGE 

all files are purged 
user is logged out 
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6.2.2 INTERPRETATION OF SYMBOLS 

Symbols can be used in several places. The previous 
examples have shown three ways a symbol can be used. 
Many rules exist by which DCL interprets symbols. Some 
of these rules follow: 

1. The DCL interpreter assumes any string input after 
the $ prompt, during an interactive session, could 
be a symbol. Therefore, the interpreter always 
checks the symbol table to see if the first string 
input is a symbol. 

2. In some DCL commands used within command 
procedures, such as IF, WRITE, and INQUIRE, the 
interpreter assumes certain strings could be 
symbols. If the string is found in the symbol 
table, the substitution is made and the command is 
executed. 

3. In other DCL commands, the interpreter must be 
informed that a string is a symbol, such as TYPE, 
PRINT, FORTRAN, and LINK. The interpreter can be 
informed in these cases by enclosing the symbol in 
single apostrophes. 

For example, in the case of the FORTRAN command, if 
the user inputs FORTRAN PI, the FORTRAN program 
will add the file_type .FOR to PI, and attempt to 
compile PI. FOR. 

To inform the interpreter that PI is really a 
symbol equated to a value (in this case, the name 
of the file), PI should be enclosed in quotes. The 
command input should be FORTRAN »P1*. The 
interpreter substitutes the value equated to PI; 
the FORTRAN program adds the file_type of .FOR, and 
the correct file is compiled. 
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For most DCL commands, the DCL interpreter must be 
informed (by using apostrophes) that a string is a 
symbol. If the documentation states that the input 
string may be a symbol, then no apostrophes are needed. 
For example, look at the documentation for IF and 
WRITE, using the HELP command as follows: 

$HELP IF parameters 

$HELP WRITE parameters 

Contrast that documentation with the information output 
for the FORTRAN command : 

$HELP FORTRAN parameters 



CHAPTER 7 
PRODUCING FORMATTED TEXT OUTPUT 



The RUNOFF utility is a text formatter. The utility accepts 
an input file and produces an output file. The input file 
contains text and RUNOFF formatting commands. The output 
file contains the formatted text. The formatted output file 
includes line feeds and form feeds at appropriate points for 
output on a line printer. By learning and using a few 
RUNOFF commands, users can produce professional looking 
text. 
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7.1 USING RUNOFF 

To use the RUNOFF utility, the following steps should be 
taken : 

1. Create the input file using an editor 

- file_type should be .RNO 

2. Exit the editor, saving the contents 

3. Create the formatted output file by using the command: 

$RUNOFF file_name 

4. Print or type the output file 

- file_type is .MEM 

While the RUNOFF utility is processing the input file, it 
may encounter incorrect commands. If this occurs, an error 
message will be output describing the error. The message 
usually includes the number of the line in the input file 
where the error occurred. To correct the error, the input 
file must be modified using an editor. After modification, 
the new version of the input file should be processed by 
RUNOFF to produce a new output file. 

When the input file has been processed successfully, the 
output file should be examined. If the output is formatted 
as intended, a final copy can be printed. Otherwise, the 
input file should be modified with an editor to reflect any 
corrections, and the new version of the input file should be 
processed by RUNOFF. These steps should be repeated until 
the output file is acceptable. 

Several qualifiers are available to be used with the RUNOFF 
command. Use the DCL HELP utility to learn more about these 
qualifiers. 
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7.2 INPUT FILES 

RUNOFF commands always begin with a period (.)• This period 
must appear in the first column followed by the command (no 
space between period and first word of command). 

Some RUNOFF commands are normally included before or after 
text. Others are usually included at the beginning of the 
input file rather than repetitively within the file. Some 
special commands called symbols appear within text strings. 
Most commands are input in one of the following formats: 

1. .command 

2. .command number 

3. .command; TEXT 

4. .command 
TEXT 

5. .command ;TEXTsymbolTEXTsymbolTEXT 

The next section of this chapter contains examples of input 
files and their corresponding output files. Tables listing 
all commands used can be found in the section following the 
example listings. A few commands are discussed further 
within the examples. Some of the output files included 
several form feeds to display the action of RUNOFF commands. 
These form feeds will be indicated by the following (which 
would not normally be seen in an output file) : 



<Form Feed> 
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.page size 58,70 

.title EXAMPLE 1 

•first title 

.autoparagraph 

.set paragraph 0,1,2 

.flags bold 

•center ; Introduction 

•blank 2 

This is example number one. This paragraph will be 
automatically formatted by RUNOFF so all lines will 
look like they are the same length. Notice that the 
.autoparagraph command is set at the beginning of the 
file. Since this paragraph begins with a space, it 
will be formatted as a new paragraph. 

This is a new paragraph. RUNOFF starts a new paragraph 
if a blank line or a space at the beginning of a line 
are read. 

All paragraphs are output with the .set paragraph 
format. Therefore; 

.list "o" 

.le; Paragraphs are not indented 

.le;One blank line is output before each paragraph 

.le;If only one line of a paragraph can fit on a page, 

a form feed is done first. 

.end list 

To make the input file easy to read, paragraphs 
should be separated by a blank line ~*and\* begun with 
a space. (If this file were processed by RUNOFF, and 
the resulting file were printed, the 'and' in the 
previous sentence would be bolded.) 

The other commands listed at the beginning of this 
file are: 

.list 

.le;_. title 
,le;_. first title 
• le;_. flags bold 
,le;_. center 
•le;_.page size 
.end list 
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EXAMPLE 1 Page 1 

Introduction 



This is example number one. This paragraph will be automatically 
formatted by RUNOFF so all lines will look like they are the same 
length. Notice that the .autoparagraph command is set at the 
beginning of the file. Since this paragraph begins with a space, it 
will be formatted as a new paragraph. 

This is a new paragraph. RUNOFF starts a new paragraph if a blank 
line or a space at the beginning of a line are read. 

All paragraphs are output with the .set paragraph format. Therefore; 

o Paragraphs are not indented 

o One blank line is output before each paragraph 

o If only one line of a paragraph can fit on a page, a form 
feed is done first. 

To make the input file easy to read, paragraphs should be separated by 
a blank line and begun with a space. (If this file were processed 
by RUNOFF, and the resulting file were printed, the 'and* in 
the previous sentence would be bolded.) 

The other commands listed at the beginning of this file are: 

1. .title 

2. .first title 

3. .flags bold 

4. .center 

5. .page size 
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.page size 20,70 !Range of values is: length, 13 - 9999 

•1 width, 3 - 150 

.title EXAMPLE 2 

.set paragraph 5,1,2 

.spacing 2 JCauses all lines in the output file 

•! to be double-spaced 

.center ; Introduction 

.paragraph 

This paragraph begins with an indentation of 5 spaces, as 
specified in the .set paragraph command. The title, EXAMPLE 2, 
should not appear until the second page of this document. 
When 20 lines have been entered on this page, the RUNOFF 
formatter will automatically insert a form feed into the output 
file, and begin a new page. 

.spacing 1 IChanges the spacing to single spacing again 

.! Notice that comments do not appear in the output file 

.header level 1 Discussion of header levels and paragraphs 

.paragraph 

Notice that the title, 'DISCUSSION OF HEADER LEVELS AND 
PARAGRAPHS', follows the number 1.0 in the output file. 
A new section of text, usually discussing the item described 
in the title, begins after the section header. Sections 
are set apart by blank lines before and after the number and 
name of the sections. (Notice that this paragraph is also 
indented by 5 spaces, and that it is necessary to use the 
.paragraph command to indicate a new paragraph.) If the 
.paragraph command is not used, and .autoparagraph is not 
set, all text will be included in the same paragraph. 
Notice that if .autoparagraph was set, this paragraph would 
be set apart as a separate paragraph. Since it is not set, 
this paragraph is included as part of the preceding paragraph. 

.header level 2 More discussion of paragraphs 

.paragraph 3,1,2 

The .paragraph command can be used to change the indentation 
and other characteristics of paragraphs also, 
.paragraph 

Notice that all letters in the top header level are 
capitalized by default, and the first letters of the second 
level are capitalized. 

.header level 3 displaying header level 1 characteristics 

.paragraph 
For third level header levels, the first character of each 
word in the title is capitalized, and the title is followed 
by a hyphen. 
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Introduction 

This paragraph begins with an indentation of 5 spaces, as 
specified in the .set paragraph command. The title, EXAMPLE 2, should 
not appear until the second page of this document. When 20 lines have 
been entered on this page, the RUNOFF formatter will automatically 
insert a form feed into the output file, and begin a new page. 

<Form Feed> 

EXAMPLE 2 Pa< 3 e 2 

1.0 DISCUSSION OF HEADER LEVELS AND PARAGRAPHS 

Notice that the title, 'DISCUSSION OF HEADER LEVELS AND 
PARAGRAPHS', follows the number 1.0 in the output file. A new section 
of text, usually discussing the item described in the title, begins 
after the section header. Sections are set apart by blank lines 
before and after the number and name of the sections. (Notice that 
this paragraph is also indented by 5 spaces, and that it is necessary 
to use the .paragraph command to indicate a new paragraph.) If the 
.paragraph command is not used, and .autoparagraph is not set, all 
text will be included in the same paragraph. Notice that if 
•autoparagraph was set, this paragraph would be set apart as a 
separate paragraph. Since it is not set, this paragraph is included 
as part of the preceding paragraph. 

<Form Feed> 

EXAMPLE 2 Page 3 

1.1 More Discussion Of Paragraphs 

The .paragraph command can be used to change the indentation and 
other characteristics of paragraphs also. 

Notice that all letters in the top header level are capitalized by 
default, and the first letters of the second level are capitalized. 

1.1.1 Displaying Header Level 1 Characteristics - 

For third level header levels, the first character of each word in 
the title is capitalized, and the title is followed by a hyphen. 
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.page size 58,70 
.title EXAMPLE 3 
.first title 
.autoparagraph 
.set paragraph 0,1,2 
.center ; INTRODUCTION 
.blank 2 

In many types of documents, reports, and memos, lists of items 
must be created. When creating a list, items are usually set 
apart by numbering, or bulleting each item. These methods are 
shown in Example#l. This example shows other methods of 
identifying list elements by using the .display element command. 
The colors of the United States of America's flag are: 

.blank 2 

.indent 2;Lowercase letters: 

.list 

.display element " ",LL," " 

.le;red 

.le;white 

.le;blue 

.end list 

.blank 2 

.indent 2;Lowercase letters followed by a period: 
.list 

.display element n W ,LL,"." 

.le;red 

.le;white 

.le;blue 

.end list 

.blank 2 

.indent 2;Uppercase letters surrounded by parentheses: 
.list 

.display element " (" ,LU,") " 

.le;red 

.le;white 

.le;blue 

.end list 

.blank 2 

• indent 2 /Lowercase Roman numerals: 

.list 

.display element " ",RL,"." 

.le;red 

•le;white 

.le;blue 

.end list 
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EXAMPLE 3 Page 1 

INTRODUCTION 



In many types of documents, reports, and memos, lists of items must be 
created. When creating a list, items are usually set apart by 
numbering, or bulleting each item. These methods are shown in 
Example 1. This example shows other methods of identifying list 
elements by using the .display element command. The colors of the 
United States of America's flag are: 

Lowercase letters: 
a red 
b white 
c blue 



Lowercase letters followed by a period: 

a. red 

b. white 

c. blue 

Uppercase letters surrounded by parentheses 

(A) red 

(B) white 

(C) blue 

Lowercase Roman numerals: 
i . red 
ii. white 
iii. blue 
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.page size 58,70 
.title EXAMPLE 4 
.first title 
.subtitle 
.autosubtitle 
.autoparagraph 
.set paragraph 2,1,2 
.center ; INTRODUCTION 



Sever 
text i 
.blank 
.list 
.le 
.le 
.le 
.le 
.le 
.le 
.end 1 

.note 



al commands are used to center, set apart, or display 
n unconventional manners. The commands include: 

1 
0,"-" 
literal 
end literal 
note 

end note 
right margin _# 
left margin _# 
ist 



The notes command is used to set text apart from other 
text by indenting the text an equal distance from each 
margin. The word NOTE is placed before the indented text. 



.end note 



.left margin +2 
.right margin -2 
.blank 1 
•center ;NOTE 

To create a note that appears differently from the normal 
NOTE command's output, the .left margin and right margin 
commands can be used. These commands reset the margin, 
and all text is then formatted within the new margins. 
The margins can be reset to the original margins at any 
time, or they can be reset to other new margins. 

right margin +2 

left margin -2 

blank 1 

literal 

Some text is required to appear 
in a certain format regardless of what the margins are. 
For this purpose, the .literal command 
is used. Text following the .literal 
command appears in the output file to be identical to 
the text in the input file until a .end literal command 
is reached, 
.blank 2 
Notice that commands are ignored within a literal. 

.end literal 
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EXAMPLE 4 Page 1 



INTRODUCTION 

Several commands are used to center, set apart, or display text in 
unconventional manners. The commands include: 

.literal 
•end literal 

- .note 

- .end note 
.right margin # 
.left margin # 



NOTE 

The notes command is used to set text 
apart from other text by indenting the 
text an equal distance from each margin. 
The word NOTE is placed before the 
indented text. 



NOTE 

To create a note that appears differently from the normal NOTE 
command's output, the .left margin and right margin commands can 
be used. These commands reset the margin, and all text is then 
formatted within the new margins. The margins can be reset to the 
original margins at any time, or they can be reset to other new 
margins. 

Some text is required to appear 
in a certain format regardless of what the margins are. 
For this purpose, the .literal command 
is used. Text following the .literal 
command appears in the output file to be identical to 
the text in the input file until a .end literal command 
is reached, 
.blank 2 
Notice that commands are ignored within a literal. 
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require "FORMAT. RNO" 
title EXAMPLE 5 
number chapter 5 



! 



The FORMAT. RNO file is listed below. It contains the 
general formatting information used by this example: 

Contents of FORMAT. RNO 

•page size 58,70 

.first title 

•subtitle 

•autosubtitle 

.autoparagraph 

•set paragraph 2,1,2 

.center ; INTRODUCTION 



.header level 1 Chapters 

The output of 
the .chapter command can be seen by looking at the beginning 
of each chapter. The .number chapter n command was used at 
the beginning of each chapter to indicate the chapter number. 
The new number was then incorporated as part of the page 
identification. 

.page 

Notice that a form feed is done even though 58 lines have not 
been output because of the .page command. 

.header level 2 Layout 
The default was used for the .layout command, and all pages 
are numbered using decimal numbers. Notice that the first 
header level is used as the subtitle. 



.page 

.autosubtitle 2 

.header level 2 Commands not shown in examples 

Notice that the second header level title is used as the 
subtitle because of the .autosubtitle command. 



These examples have contained 
most of the commands listed in the following tables. The 
commands not depicted are more advanced. Users should be 
able to read the syntax of the command from the table to 
incorporate it in their input file. 
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INTRODUCTION 



1.0 CHAPTERS 

The output of the .chapter command can be seen by looking at the 
beginning of each chapter. The .number chapter n command was used at 
the beginning of each chapter to indicate the chapter number. The new 
number was then incorporated as part of the page identification. 



<Form Feed> 



EXAMPLE 5 Page 5-2 

CHAPTERS 

Notice that a form feed is done even though 58 lines have not been 
output because of the .page command. 

1.1 Layout 

The default was used for the .layout command, and all pages are 
numbered using decimal numbers. Notice that the first header level is 
used as the subtitle. 



<Form Feed> 
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Commands Not Shown In Examples 

1.2 Commands Not Shown In Examples 

Notice that the second header level title is used as the subtitle 
because of the .autosubtitle command. 

These examples have contained most of the commands listed in the 
following tables. The commands not depicted are more advanced. Users 
should be able to read the syntax of the command from the table to 
incorporate it in their input file. 



PRODUCING FORMATTED TEXT OUTPUT Page 7-14 

7.3 SUMMARY OF RUNOFF COMMANDS 

Commonly used RUNOFF commands are summarized in several 
tables in the next section. Commands are listed in tables 
by function for reference purposes. 

The tables contain commands affecting the following: 

o Table 7-1 - Paragraph format 

o Table 7-2 - Text format 

o Table 7-3 - Creation of lists 

o Table 7-4 - Symbols 

o Table 7-5 - Recognition of symbols 

o Table 7-6 - Title information 

o Table 7-7 - Amount of text on a page 

o Table 7-8 - Page identification 

o Table 7-9 - General format 



NOTE 

Any of the commands listed in the tables can be 
included anywhere in the input file. Abbreviations 
for each command are included in parentheses under 
each command although command files are more 
readable and self -documented when abbreviations are 
not used. Optional portions of commands are 
enclosed in square brackets (e.g. [optional] ) 
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Table 7-1 Commands affecting paragraph format 
Command Effect on output file 



.autoparagraph 
(.ap) 



.no autoparagraph 
(.nap) 

.set paragraph [i,v,t] 
(.spr) 



.paragraph [i,v,t] 
(•P) 



Enables the automatic recognition 
of paragraphs. A new paragraph is 
begun in the output file if a blank 
line or a line beginning with a 
space is read in the input file 

Disables automatic paragraph 
recognition (default) 

Describes the format of each paragraph, 
i designates how many spaces to indent 
before text begins. v designates the 
number of vertical line feeds before a 
paragraph, t designates how many lines 
can be output before a form feed must 
be done. If the specified number of 
lines can not be output, the form feed 
is output first; then the paragraph. 
Default is 5,1,2. 

Specifies that the following text is a 
new paragraph. Needed only if 
.autoparagraph is not specified. 
Can reset paragraph characteristics 
(see .set paragraph) 
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Table 7-2 Commands used to format specific portions of text 
Command Effect on output file 



.center ;text 



.indent n 
(•i) 



.left margin n 
Mm) 



•right margin n 
(.rm) 



Center the specified text. Text may 
follow .center; or may be input on 
the subsequent line. Only one line 
will be centered. 

Indent next line n spaces to the right 
or left (if n is negative) of the left 
margin. 

Set the left margin to column n or; 
Move the left margin: 

- to the right if n is positive 

- to the left if n is negative 

Set the right margin to column n or; 
Move the right margin: 

- to the right if n is positive 

- to the left if n is negative 



.break 
(.br or .) 



End the current line without filling 
or justifying it and begin new line. 



.literal 
(.It) 



.end literal 
(.el) 

.note [title] 
.end note 

(.n and .en) 



Specify that the subsequent text is 
not to be formatted. It will appear 
in the output file exactly as it 
appears in the input file. (Caution: 
The TAB is the exception. TAB is 
is translated as a space. Use the 
SPACE bar instead of TAB.) 

Causes RUNOFF to begin formatting 
text again. 

Indent text between .note and .end 
note from both margins. Precedes and 
follows the text with blank lines. 
Also precedes the text with the word 
NOTE (or optional title centered on 
a line. 
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Table 7-3 Commands used for the creation of lists 
Command Effect on output file 



.list n/'c" 
(.Is) 



Begin a list with n blank lines between 
each item. Each item begins with the 
character indicated by "c" , by default, 
decimal numbers incremented by 1. 
Typical values for "c" are "o" , or " ", 



.display element "a" , "b" , "c" Identify list items. 

(.die) 

"a" and "c" are single characters 
to be displayed before and/or after 
"b" 

"b" is defined using a code 
chosen from the following list: 

Code Output 

D Decimal numbers 

RU Roman uppercase numerals 

RL Roman lowercase numerals 

RM Roman mixed case numerals 

LU Letters, uppercase 

LL Letters, lowercase 

LM Letters, mixed case 

(mixed case - 1st letter 
only is uppercase) 



.list element/text 
(.le) 

•end list 
(.els) 



Specifies item to be listed. This 
command must precede each item. 

Identifies the end of the list. 
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Table 7-4 Symbols used within text lines to format text 
Symbol Effect on output file 

The following symbols are automatically enabled: 

Underscore. Causes any character following it 
~ to be accepted as normal text. Useful when a 

special symbol is to be included in text as 
text. 

# Number sign. Outputs exactly one space. 

& Ampersand. Underlines the character 

immediately following it. 

~&text\& The text between the up-arrow ampersand 

and backslash ampersand symbols is underlined. 

The following symbols must be enabled to have any effect: 

* Asterisk. Causes the character immediately 

following it to be bolded. (Appears darker 
if output file is printed) 

"*text\* The text between the up-arrow asterisk and 

backslash ampersand symbols is bolded. 

% Percent sign. When inserted between two 

characters, causes the preceding character 
to be overstruck by the subsequent character. 
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Table 7-5 Commands used to enable/disable recognition of symbols 
Command Effect on output file 



.flags bold 
(.fl bold) 

.no flags bold 
(.nfl bold) 

.flags overstrike 
(.fl overstrike) 



Enables recognition of * as the bolding 
command . 

Disables recognition of * as bolding command 



Enables recognition of % as the overstrike 
command . 



.no flags overstrike Disables recognition of % as the overstrike 
(.nfl overstrike) command. 
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Table 7-6 Commands affecting titles output on pages 
Command Effect on output file 



•title text 
(.t) 



.subtitle text 
(.st) 



•first title 
(.ft) 

•autosubtitle n 
( .ast) 



•noautosubtitle 
(.nast) 

•header level n text 
(•hi) 



•display level code 



Includes the specified title, TEXT, 
as the first line on each page 
except the first page 

Enables automatic subtitling. 

If a subtitle, TEXT, is specified, 

includes it under the title on every 

page except the first page. 

If .autosubtitle is also input 

as a command, includes header level 

titles as subtitles instead 

Causes the title and subtitle to be 
output on the first page also 

Causes header level titles up to and 
including the level indicated by n 
(default is 1) to be used as subtitles 
if .subtitle is also input as a command 

Disables autosubtitling 



Allows use of section numbering: 
Value of n: Type of Output 

1 2.1 text 
2.2 text 

2 2.1.1 text 

2.1.2 text 

2.1.3 text 

3 2.1.1.1 text 

2.1.1.2 text 

2.1.1.3 text 

Displays header level numbers in format 
according to code (see .display element 
for codes). Default is decimal numbers. 
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Table 7-7 Commands affecting amount of text on a page 
Command Effect on output file 



.page size l f w 
(.ps) 



.page 

(•pg) 

.spacing n 
(.sp) 



.test page n 
(.tp) 

.blank n 



Determines the size of each page. 
1 designates the length (lines per 
page) , and w designates the width 
(characters per line). Default is 
58,60. 

Starts a new page 



Establishes spacing between lines 
(l=single space, 2=double space, 
etc. up to 5) 

Start a new page if there are less 
than n lines left on current page 



Output n blank lines 
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Table 7-8 Commands affecting Page Identification 
Command Effect on output file 



.no number 
(.nnm) 

.number page n 
(.nmpg) 



.display number code 
(.dnm) 



Disable listing (but not counting) of 
page numbers. 

Resume sequential page numbering, 
using page number n as first page. 
If n is not specified, use current 
page number . 

Display page numbers in format 
according to code (see .display 
element for code) . Default is 
decimal numbers. 



.chapter [title] 
(.ch) 

.number chapter n 
(.nmch) 



.display chapter code 
(.dch) 



Start a new chapter on a new page 
using title specified. 

Specify the number of the current 
chapter. If n is not specified, 
1 is used. 

Display chapter numbers in format 
according to code (see .display 
element for code) . Default is 
decimal numbers. 
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Table 7-9 Commands affecting overall format of output file 
Command Effect on output file 



.require "file" 
(.req) 



.layout n, [m] 
(.lo) 



. ! comment 



Causes the specified file to be read and 

processed. The file usually contains commands 

to set up the general format of the output 
file. 

Specifies the location of the title/subtitle 
and page identification. 

Use one of the following codes for n (0 is 
default) : 

Title/subtitle flush left 
Page id flush right 

1 Title/subtitle centered at top of page 
Page id centered at bottom of page 

2 Title/subtitle flush right (odd page) 

and flush left (even page) 
Page id centered at bottom of page 

3 Title/subtitle flush left 

Page id flush right and page numbers 
incremented by 1 centered at bottom 
of each page. (e.g. at top, page 
number is 4-7; at bottom, page 
number is 132) 

The second argument, m, is used to indicate 
the number of blank lines which should be 
inserted between the page id at the bottom 
of the page, and the last line of text, 
(required for codes 1 to 3) 

To include comments which will not appear 
in the formatted output file 



CHAPTER 8 
MISCELLANEOUS VAX/VMS UTILITIES 



The MAIL and PHONE utilities allow interactive users to 
communicate on-line. The MAIL utility is used to send 
messages to one or more users on a system (or to users on 
another system via DECnet) in the same way a person would 
mail a letter. The PHONE utility allows users to 
communicate interactively in the same way a person would use 
a telephone. 

8.1 USING THE MAIL UTILITY 

All mail sent to a user is stored in a file, MAIL. MAI, in 
the user's top-level directory. This file is accessed by 
the MAIL utility. 

To use the MAIL utility, enter the DCL command MAIL. The 
mail utility will be invoked, and the MAIL prompt will be 
output. If the HELP command is entered, all available MAIL 
commands are listed. Help can be obtained on any of the 
commands listed by using the HELP facility in the same 
manner as the DCL HELP facility. 

Most MAIL commands ask for the name of the user you are 

sending the mail to, and the subject of the message. The 

user name can be preceded by a node name if the user is 
working on another system. 

Examples of user names: 

Smith 

NODEA: : Jones 
GREAT: :Howeser 

Several MAIL commands will not work unless you are reading 
or have just read a piece of mail. For example, the FORWARD 
command forwards the mail just read to the specified user. 
The discussion of the command output by HELP should be read 
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carefully to notice which commands are in this category. 
Table 8-1 lists the major MAIL commands and their functions. 



Table 8-1 MAIL commands 
Function 



Command 



Send mail to another user 

List all available messages 

Display a message on the terminal 

Copy the current message to the printer 

Copy the current message to a file 

Send a copy of the current message to 
another user 

Reply to the current message 

Remove the current message from 
the mail file 



SEND [file_name] 

DIRECTORY 

READ [#] 

PRINT 

FILE file_name 

FORWARD 

REPLY 
DELETE 



When a message is sent to a user, the user is notified by 
the MAIL utility. A message will appear on the screen, 'new 
mail from user_name'. The user_name in the message is the 
name of the user who sent the mail. 

If: 

o The user does not read the mail 
o The user is not logged in when the mail is sent 

then the MAIL utility keeps track of the number of messages 
sent. When the user logs in again, the MAIL utility sends a 
message to his/her terminal indicating the number of 
messages that have not been read. 

To list the available messages, the DIRECTORY command should 
be used. The READ command accepts a number as a parameter 
so a specific message can be read. When the user enters 
MAIL and specifies the READ command without a number, MAIL 
displays the latest messages received. 
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$MAIL 

MAIL> SEND 
to: Joe Smith 

subj : Sending example of the latest version of GRADES 
Enter your message below. Press CTRL/Z when complete, CTRL/C to quit 

Hi . . . I am sending you a copy of the latest version of 
the GRADES program in the next message for your interest. 



MAIL> SEND GRADES. FOR 
to: Joe Smith 
subj : Here it is! 

MAIL> EXIT 
$ 

To send a file or message to more than one user, list the 
user names (separated by commas) after the to: prompt, or 
specify a distribution list. Distribution lists are lists 
of user names (separated by commas or on separate lines) . 
These lists are stored in files of file_type .DIS. Create a 
distribution list by using an editor. Use the @ command to 
specify the file. For example, 

Contents of NAMES. DIS: 

SMITH, JONES, BARKER 

$MAIL 

MAIL> SEND Meeting.dat 

to: @NAMES 

subj : Meeting tomorrow 

MAIL> EXIT 

$ 
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8.2 USING THE PHONE UTILITY 

To PHONE another user, enter the PHONE utility by typing the 
DCL command, PHONE. The information on the terminal screen 
will be replaced by a screen formatted for the use of PHONE. 
The PHONE format includes: 

o A command line - beginning with a % prompt. 

o A section of the screen for the caller's use. 

o The lower section of the screen for the callee's use. 

The HELP utility in PHONE will list all PHONE commands if 

HELP is entered on the command line (after the % prompt) . 

Help can be obtained on any PHONE command by entering HELP 
command . 

Users can phone other users, put calls on hold, send short 

messages using the MAIL utility while in PHONE, send files 

to other users, and refuse to accept calls. Commands are 

listed in Table 8-2. 

DIAL is the default command. To phone another user, enter 
DIAL username on the command line (or simply enter the 
username). Users on other nodes can be dialed via DECnet by 
specifying the node (node : :username) . 

PHONE rings the other users terminal. If the other user 
enters the DCL command, PHONE, following by the PHONE 
command, ANSWER, communication can begin. Users enter text 
which will appear in the top half of their own terminal 
screen and the bottom half of the other users screen. 
Several lines of text can be entered. As the user enters 
text, the text appears on the other user's terminal. 

All text entered after the call has begun is assumed to be 
part of the message. Commands must be entered on the 
command line only. To get to the command line while 
entering a message, the switchhook character should be 
entered. The default switchhook character is the percent 
sign (%) . One command may be entered; then the user is 
returned to the message area. This is useful for entering 
commands such as HOLD or REJECT (see Table 8-2) . 
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Table 8-2 PHONE Commands 
Function 



Command 



Place a call (Default) 

Answer a call while in PHONE 

Display a list of available users 
(including users on other nodes) 

Send the contents of a file to 
all users involved in the conversation 

Place a caller on hold 

Reject a call from a caller 

Take a caller off hold 

Send a short (one line) message 
to a user who is unavailable for 
a PHONE conversation 

Hangup your own phone 

Obtain help on PHONE commands 



DIAL username 

ANSWER 

DIRECTORY [node::] 

FACSIMILE file_name 

HOLD 
REJECT 
UNHOLD 
MAIL 

HANGUP (or CTRL-Z) 
HELP 
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